Mix.SCM — Mix v1.16.3

Search documentation of Mix

# View Source Mix.SCM behaviour (Mix v1.16.3)

This module provides helper functions and defines the behaviour required by any source code manager (SCM) used by Mix.

# Summary

## Types

opts()
t()

A module implementing the `Mix.SCM` behaviour.

## Callbacks

accepts_options(app, opts)

This behaviour function receives a keyword list of `opts` and should return an updated list in case the SCM consumes the available options. For example, when a developer specifies a dependency

checked_out?(opts)

This behaviour function returns a boolean if the dependency is available.

checkout(opts)

This behaviour function checks out dependencies.

equal?(opts1, opts2)

Receives two options and must return `true` if they refer to the same repository. The options are guaranteed to belong to the same SCM.

fetchable?()

Returns a boolean if the dependency can be fetched or it is meant to be previously available in the file system.

format(opts)

Returns a string representing the SCM. This is used when printing the dependency and not for inspection, so the amount of information should be concise and easy to spot.

format_lock(opts)

Returns a string representing the SCM. This is used when printing the dependency and not for inspection, so the amount of information should be concise and easy to spot.

lock_status(opts)

This behaviour function checks the status of the lock. In particular, it checks if the revision stored in the lock is the same as the repository it is currently in.

managers(opts)

Returns the usable managers for the dependency. This can be used if the SCM has extra knowledge of the dependency, otherwise it should return an empty list.

update(opts)

This behaviour function updates dependencies. It may be called by `deps.get` or `deps.update`.

## Functions

append(mod)

Appends the given SCM module to the list of available SCMs.

available()

Returns all available SCMs. Each SCM is tried in order until a matching one is found.

delete(mod)

Deletes the given SCM from the list of available SCMs.

prepend(mod)

Prepends the given SCM module to the list of available SCMs.

# Types

Link to this type

# opts()

View Source

    @type opts() :: keyword()

Link to this type

# t()

View Source

    @type t() :: module()

A module implementing the `Mix.SCM` behaviour.

# Callbacks

Link to this callback

# accepts_options(app, opts)

View Source

    @callback accepts_options(app :: atom(), opts()) :: opts() | nil

This behaviour function receives a keyword list of `opts` and should return an updated list in case the SCM consumes the available options. For example, when a developer specifies a dependency:

    {:foo, "0.1.0", github: "foo/bar"}

Each registered SCM will be asked if they consume this dependency, receiving `[github: "foo/bar"]` as argument. Since this option makes sense for the Git SCM, it will return an update list of options while other SCMs would simply return `nil`.

Link to this callback

# checked_out?(opts)

View Source

    @callback checked_out?(opts()) :: boolean()

This behaviour function returns a boolean if the dependency is available.

Link to this callback

# checkout(opts)

View Source

    @callback checkout(opts()) :: any()

This behaviour function checks out dependencies.

If the dependency is locked, a lock is received in `opts` and the repository must be check out at the lock. Otherwise, no lock is given and the repository can be checked out to the latest version.

It must return the current lock.

Link to this callback

# equal?(opts1, opts2)

View Source

    @callback equal?(opts1 :: opts(), opts2 :: opts()) :: boolean()

Receives two options and must return `true` if they refer to the same repository. The options are guaranteed to belong to the same SCM.

Link to this callback

# fetchable?()

View Source

    @callback fetchable?() :: boolean()

Returns a boolean if the dependency can be fetched or it is meant to be previously available in the file system.

Local dependencies (i.e. non-fetchable ones) are automatically recompiled every time the parent project is compiled.

Link to this callback

# format(opts)

View Source

    @callback format(opts()) :: String.t()

Returns a string representing the SCM. This is used when printing the dependency and not for inspection, so the amount of information should be concise and easy to spot.

Link to this callback

# format_lock(opts)

View Source

    @callback format_lock(opts()) :: String.t() | nil

Returns a string representing the SCM. This is used when printing the dependency and not for inspection, so the amount of information should be concise and easy to spot.

If nil is returned, it means no lock information is available.

Link to this callback

# lock_status(opts)

View Source

    @callback lock_status(opts()) :: :mismatch | :outdated | :ok

This behaviour function checks the status of the lock. In particular, it checks if the revision stored in the lock is the same as the repository it is currently in.

It may return:

- `:mismatch` - if the lock doesn't match and we need to simply move to the latest lock

- `:outdated` - the repository options are outdated in the lock and we need to trigger a full update

- `:ok` - everything is fine

The lock is sent via `opts[:lock]` but it may not always be available. In such cases, if the SCM requires a lock, it must return `:mismatch`, otherwise simply `:ok`.

Note the lock may also belong to another SCM and as such, an structural check is required. A structural mismatch should always return `:outdated`.

Link to this callback

# managers(opts)

View Source

    @callback managers(opts()) :: [atom()]

Returns the usable managers for the dependency. This can be used if the SCM has extra knowledge of the dependency, otherwise it should return an empty list.

Link to this callback

# update(opts)

View Source

    @callback update(opts()) :: any()

This behaviour function updates dependencies. It may be called by `deps.get` or `deps.update`.

In the first scenario, a lock is received in `opts` and the repository must be updated to the lock. In the second, no lock is given and the repository can be updated freely.

It must return the current lock.

# Functions

Link to this function

# append(mod)

View Source

Appends the given SCM module to the list of available SCMs.

Link to this function

# available()

View Source

Returns all available SCMs. Each SCM is tried in order until a matching one is found.

Link to this function

# delete(mod)

View Source (since 1.16.2)

Deletes the given SCM from the list of available SCMs.

Link to this function

# prepend(mod)

View Source

Prepends the given SCM module to the list of available SCMs.