<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="generator" content="ExDoc v0.19.1"> <title>Mix.SCM – Mix v1.7.2</title> <link rel="stylesheet" href="dist/app-240d7fc7e5.css" /> <link rel="canonical" href="https://hexdocs.pm/mix/v1.7/Mix.SCM.html" /> <script src="dist/sidebar_items-0c0044e6e4.js"></script> </head> <body data-type="modules"> <script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script> <div class="main"> <button class="sidebar-button sidebar-toggle"> <span class="icon-menu" aria-hidden="true"></span> <span class="sr-only">Toggle Sidebar</span> </button> <button class="sidebar-button night-mode-toggle"> <span class="icon-theme" aria-hidden="true"></span> <span class="sr-only">Toggle Theme</span> </button> <section class="sidebar"> <a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink"> <div class="sidebar-projectDetails"> <h1 class="sidebar-projectName"> Mix </h1> <h2 class="sidebar-projectVersion"> v1.7.2 </h2> </div> <img src="assets/logo.png" alt="Mix" class="sidebar-projectImage"> </a> <form class="sidebar-search" action="search.html"> <button type="submit" class="search-button"> <span class="icon-search" aria-hidden="true"></span> </button> <input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" /> </form> <ul class="sidebar-listNav"> <li><a id="extras-list" href="#full-list">Pages</a></li> <li><a id="modules-list" href="#full-list">Modules</a></li> <li><a id="exceptions-list" href="#full-list">Exceptions</a></li> <li><a id="tasks-list" href="#full-list">Mix Tasks</a></li> </ul> <div class="gradient"></div> <ul id="full-list" class="sidebar-fullList"></ul> </section> <section class="content"> <div class="content-outer"> <div id="content" class="content-inner"> <h1> <small class="visible-xs">Mix v1.7.2</small> Mix.SCM <small>behaviour</small> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L1" title="View Source" class="view-source" rel="help"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </h1> <section id="moduledoc"> <p>This module provides helper functions and defines the behaviour required by any source code manager (SCM) used by Mix.</p> </section> <section id="summary" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#summary"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Summary </h1> <div class="summary-types summary"> <h2> <a href="#types">Types</a> </h2> <div class="summary-row"> <div class="summary-signature"> <a href="#t:opts/0">opts()</a> </div> </div> </div> <div class="summary-functions summary"> <h2> <a href="#functions">Functions</a> </h2> <div class="summary-row"> <div class="summary-signature"> <a href="#append/1">append(mod)</a> </div> <div class="summary-synopsis"><p>Appends the given SCM module to the list of available SCMs</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#available/0">available()</a> </div> <div class="summary-synopsis"><p>Returns all available SCMs. Each SCM is tried in order until a matching one is found</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#prepend/1">prepend(mod)</a> </div> <div class="summary-synopsis"><p>Prepends the given SCM module to the list of available SCMs</p> </div> </div> </div> <div class="summary-callbacks summary"> <h2> <a href="#callbacks">Callbacks</a> </h2> <div class="summary-row"> <div class="summary-signature"> <a href="#c:accepts_options/2">accepts_options(app, opts)</a> </div> <div class="summary-synopsis"><p>This behaviour function receives a keyword list of <code class="inline">opts</code> and should return an updated list in case the SCM consumes the available options. For example, when a developer specifies a dependency</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:checked_out?/1">checked_out?(opts)</a> </div> <div class="summary-synopsis"><p>This behaviour function returns a boolean if the dependency is available</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:checkout/1">checkout(opts)</a> </div> <div class="summary-synopsis"><p>This behaviour function checks out dependencies</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:equal?/2">equal?(opts1, opts2)</a> </div> <div class="summary-synopsis"><p>Receives two options and must return <code class="inline">true</code> if they refer to the same repository. The options are guaranteed to belong to the same SCM</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:fetchable?/0">fetchable?()</a> </div> <div class="summary-synopsis"><p>Returns a boolean if the dependency can be fetched or it is meant to be previously available in the filesystem</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:format/1">format(opts)</a> </div> <div class="summary-synopsis"><p>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</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:format_lock/1">format_lock(opts)</a> </div> <div class="summary-synopsis"><p>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</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:lock_status/1">lock_status(opts)</a> </div> <div class="summary-synopsis"><p>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</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:managers/1">managers(opts)</a> </div> <div class="summary-synopsis"><p>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</p> </div> </div> <div class="summary-row"> <div class="summary-signature"> <a href="#c:update/1">update(opts)</a> </div> <div class="summary-synopsis"><p>This behaviour function updates dependencies. It may be called by <code class="inline">deps.get</code> or <code class="inline">deps.update</code></p> </div> </div> </div> </section> <section id="types" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#types"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Types </h1> <div class="types-list"> <div class="detail" id="t:opts/0"> <div class="detail-header"> <a href="#t:opts/0" class="detail-link" title="Link to this type"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this type</span> </a> <span class="signature">opts()</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L7" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>opts() :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">keyword</a>()</pre> </div> </div> <section class="docstring"> </section> </div> </div> </section> <section id="functions" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#functions"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Functions </h1> <div class="detail" id="append/1"> <div class="detail-header"> <a href="#append/1" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">append(mod)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L140" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Appends the given SCM module to the list of available SCMs.</p> </section> </div> <div class="detail" id="available/0"> <div class="detail-header"> <a href="#available/0" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">available()</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L125" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Returns all available SCMs. Each SCM is tried in order until a matching one is found.</p> </section> </div> <div class="detail" id="prepend/1"> <div class="detail-header"> <a href="#prepend/1" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">prepend(mod)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L133" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Prepends the given SCM module to the list of available SCMs.</p> </section> </div> </section> <section id="callbacks" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#callbacks"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Callbacks </h1> <div class="detail" id="c:accepts_options/2"> <div class="detail-header"> <a href="#c:accepts_options/2" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">accepts_options(app, opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L50" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>accepts_options(app :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>(), <a href="#t:opts/0">opts</a>()) :: <a href="#t:opts/0">opts</a>() | nil</pre> </div> </div> <section class="docstring"> <p>This behaviour function receives a keyword list of <code class="inline">opts</code> and should return an updated list in case the SCM consumes the available options. For example, when a developer specifies a dependency:</p> <pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="2622418463-1">{</span><span class="ss">:foo</span><span class="p">,</span><span class="w"> </span><span class="s">"0.1.0"</span><span class="p">,</span><span class="w"> </span><span class="ss">github</span><span class="p">:</span><span class="w"> </span><span class="s">"foo/bar"</span><span class="p" data-group-id="2622418463-1">}</span></code></pre> <p>Each registered SCM will be asked if they consume this dependency, receiving <code class="inline">[github: "foo/bar"]</code> 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 <code class="inline">nil</code>.</p> </section> </div> <div class="detail" id="c:checked_out?/1"> <div class="detail-header"> <a href="#c:checked_out?/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">checked_out?(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L56" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>checked_out?(<a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">boolean</a>()</pre> </div> </div> <section class="docstring"> <p>This behaviour function returns a boolean if the dependency is available.</p> </section> </div> <div class="detail" id="c:checkout/1"> <div class="detail-header"> <a href="#c:checkout/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">checkout(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L68" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>checkout(<a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()</pre> </div> </div> <section class="docstring"> <p>This behaviour function checks out dependencies.</p> <p>If the dependency is locked, a lock is received in <code class="inline">opts</code> 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.</p> <p>It must return the current lock.</p> </section> </div> <div class="detail" id="c:equal?/2"> <div class="detail-header"> <a href="#c:equal?/2" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">equal?(opts1, opts2)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L112" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>equal?(opts1 :: <a href="#t:opts/0">opts</a>(), opts2 :: <a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">boolean</a>()</pre> </div> </div> <section class="docstring"> <p>Receives two options and must return <code class="inline">true</code> if they refer to the same repository. The options are guaranteed to belong to the same SCM.</p> </section> </div> <div class="detail" id="c:fetchable?/0"> <div class="detail-header"> <a href="#c:fetchable?/0" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">fetchable?()</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L17" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>fetchable?() :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">boolean</a>()</pre> </div> </div> <section class="docstring"> <p>Returns a boolean if the dependency can be fetched or it is meant to be previously available in the filesystem.</p> <p>Local dependencies (i.e. non-fetchable ones) are automatically recompiled every time the parent project is compiled.</p> </section> </div> <div class="detail" id="c:format/1"> <div class="detail-header"> <a href="#c:format/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">format(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L25" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>format(<a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/String.html#t:t/0">String.t</a>()</pre> </div> </div> <section class="docstring"> <p>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.</p> </section> </div> <div class="detail" id="c:format_lock/1"> <div class="detail-header"> <a href="#c:format_lock/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">format_lock(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L35" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>format_lock(<a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/String.html#t:t/0">String.t</a>() | nil</pre> </div> </div> <section class="docstring"> <p>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.</p> <p>If nil is returned, it means no lock information is available.</p> </section> </div> <div class="detail" id="c:lock_status/1"> <div class="detail-header"> <a href="#c:lock_status/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">lock_status(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L105" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>lock_status(<a href="#t:opts/0">opts</a>()) :: :mismatch | :outdated | :ok</pre> </div> </div> <section class="docstring"> <p>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.</p> <p>It may return:</p> <ul> <li><p><code class="inline">:mismatch</code> - if the lock doesn’t match and we need to simply move to the latest lock</p> </li> <li><p><code class="inline">:outdated</code> - the repository options are outdated in the lock and we need to trigger a full update</p> </li> <li><p><code class="inline">:ok</code> - everything is fine</p> </li> </ul> <p>The lock is sent via <code class="inline">opts[:lock]</code> but it may not always be available. In such cases, if the SCM requires a lock, it must return <code class="inline">:mismatch</code>, otherwise simply <code class="inline">:ok</code>.</p> <p>Note the lock may also belong to another SCM and as such, an structural check is required. A structural mismatch should always return <code class="inline">:outdated</code>.</p> </section> </div> <div class="detail" id="c:managers/1"> <div class="detail-header"> <a href="#c:managers/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">managers(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L119" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>managers(<a href="#t:opts/0">opts</a>()) :: [<a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">atom</a>()]</pre> </div> </div> <section class="docstring"> <p>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.</p> </section> </div> <div class="detail" id="c:update/1"> <div class="detail-header"> <a href="#c:update/1" class="detail-link" title="Link to this callback"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this callback</span> </a> <span class="signature">update(opts)</span> <a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/mix/lib/mix/scm.ex#L80" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> <div class="specs"> <pre>update(<a href="#t:opts/0">opts</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()</pre> </div> </div> <section class="docstring"> <p>This behaviour function updates dependencies. It may be called by <code class="inline">deps.get</code> or <code class="inline">deps.update</code>.</p> <p>In the first scenario, a lock is received in <code class="inline">opts</code> and the repository must be updated to the lock. In the second, no lock is given and the repository can be updated freely.</p> <p>It must return the current lock.</p> </section> </div> </section> <footer class="footer"> <p> <span class="line"> Built using <a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1), </span> <span class="line"> designed by <a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>. </span> </p> </footer> </div> </div> </section> </div> <script src="dist/app-a0c90688fa.js"></script> </body> </html>