Packages
--------

Packages are defined inside the ``package/`` directory. There is no explicit
limit on the total number of packages a project can have. Packages can consist
of libraries, programs or even basic assets. Package names are recommended to be
lower-case with dash-separated (``-``) separators (if needed). For example,
``package-a`` is recommended over ``PackageA`` or ``package_a``; however, the
choice is up to the developer making the releng-tool project.

When making a package, a container folder for the package as well as a package
definition file needs to be made. For example, if the package is ``package-a``,
the file ``package/package-a/package-a`` should exist. Package definition files
are Python-based, thus the following leading header is recommended:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

Inside the definition file, a series of configuration options can be set to tell
releng-tool how to work with the defined package. Each option is prefixed with
a variable-safe variant of the package name. The prefix value will be an
uppercase string based on the package name with special characters converted to
underscores. For example, ``package-a`` will have a prefix ``PACKAGE_A_``. For a
package to take advantage of a configuration option, the package definition will
add a variable entry with the package's prefix followed by the
supported option name. Considering the same package with the name ``package-a``
(and prefix ``PACKAGE_A_``), to use the |LIBFOO_VERSION|_ configuration option,
the following can be defined (``PACKAGE_A_VERSION``):

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   PACKAGE_A_VERSION='1.0.0'

More details on available configuration options are as follows.

Common package configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following outlines common configuration options available for packages.

LIBFOO_DEPENDENCIES
^^^^^^^^^^^^^^^^^^^

List of package dependencies a given project has. If a project depends on
another package, the package name should be listed in this option. This ensures
releng-tool will process packages in the proper order. The following shows an
example package ``libc`` being dependent on ``liba`` and ``libb`` being
processed first:

.. code-block:: python

   LIBC_DEPENDENCIES = ['liba', 'libb']

LIBFOO_INSTALL_TYPE
^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_INSTALL_TYPE| replace:: ``LIBFOO_INSTALL_TYPE``

Defines the installation type of this package. A package may be designed to be
built and installed for just the target area, the stage area, both or maybe in
the host directory. The following options are available for the installation
type:

====================== ===
Type                   Description
====================== ===
``host``               The host directory.
``images``             The images directory.
``staging``            The staging area.
``staging_and_target`` Both the staging an target area.
``target``             The target area.
====================== ===

The default installation type is ``target``.

.. code-block:: python

   LIBFOO_INSTALL_TYPE = 'target'

See also |LIBFOO_HOST_PROVIDES|_.

LIBFOO_LICENSE
^^^^^^^^^^^^^^
.. |LIBFOO_LICENSE| replace:: ``LIBFOO_LICENSE``

A string or list of strings outlining the license information for a package.
Outlining the license of a package is always recommended (but not required).

.. code-block:: python

   LIBFOO_LICENSE = ['GPLv2', 'MIT']

or

.. code-block:: python

   LIBFOO_LICENSE = 'Proprietary'

See also |LIBFOO_LICENSE_FILES|_.

LIBFOO_LICENSE_FILES
^^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_LICENSE_FILES| replace:: ``LIBFOO_LICENSE_FILES``

A string or list of strings identifying the license files found inside the
package sources which match up to the defined ``LICENSE`` entries
(respectively). Listing the license(s) of a package is always recommended (but
not required).

.. code-block:: python

   LIBFOO_LICENSE_FILES = [
       'LICENSE.GPLv2',
       'LICENSE.MIT',
   ]

or

.. code-block:: python

   LIBFOO_LICENSE_FILES = 'LICENSE'

See also |LIBFOO_LICENSE|_.

LIBFOO_SITE
^^^^^^^^^^^
.. |LIBFOO_SITE| replace:: ``LIBFOO_SITE``

The site where package sources/assets can be found. The site can be a URL of an
archive, or describe a source control URL such as Git or SVN. The following
outline a series of supported site definitions:

========= ===
Type      Prefix/Postfix
========= ===
Bazaar    ``bzr+``
CVS       ``cvs+``
Git       ``git+`` or ``.git``
Mercurial ``hg+``
rsync     ``rsync+``
SCP       ``scp+``
SVN       ``svn+``
URL       `(wildcard)`
========= ===

Examples include:

.. parsed-literal::

   LIBFOO_SITE = '\https://example.com/libfoo.git'
   LIBFOO_SITE = 'cvs+:pserver:anonymous@cvs.example.com:/var/lib/cvsroot mymodule'
   LIBFOO_SITE = 'svn+\https://svn.example.com/repos/libfoo/c/branches/libfoo-1.2'
   LIBFOO_SITE = '\https://www.example.com/files/libfoo.tar.gz'
   LIBFOO_SITE = {
       DEFAULT_SITE: '\https://pkgs.example.com/releases/libfoo-${LIBFOO_VERSION}.tar.gz',
       '<mode>': '\https://git.example.com/libfoo.git',
   }

A developer can also use |LIBFOO_VCS_TYPE|_ to explicitly define the version
control system type without the need for a prefix/postfix entry. The use of
a dictionary value is only useful when operating in
:ref:`development mode <development mode>`.

For more information on each type's formatting, see
:ref:`site definitions <site_definitions>`.

Using a specific type will create a dependency for a project that the respective
host tool is installed on the host system. For example, if a Git site is set,
the host system will need to have ``git`` installed on the system.

If no site is defined for a package, it will be considered a virtual package
(i.e. has no content). If applicable, loaded extensions may provide support for
custom site protocols.

Specifying a site value of ``local`` will automatically configure a VCS-type of
``local`` (see |LIBFOO_VCS_TYPE|_ for more information).

See also |LIBFOO_VCS_TYPE|_.

LIBFOO_TYPE
^^^^^^^^^^^
.. |LIBFOO_TYPE| replace:: ``LIBFOO_TYPE``

The package type. The default package type is a (Python) script-based package;
however, releng-tool also provides a series of helper package types for common
frameworks. The following outline a series of supported type definitions:

.. table::
    :widths: 50 50

    ================================ ===
    Type                             Value
    ================================ ===
    :ref:`Autotools <autotools-pkg>` ``autotools``
    :ref:`CMake <cmake-pkg>`         ``cmake``
    :ref:`Make <make-pkg>`           ``make``
    :ref:`Python <python-pkg>`       ``python``
    :ref:`SCons <scons-pkg>`         ``scons``
    :ref:`Script <script-pkg>`       ``script``
    ================================ ===

For example:

.. code-block:: python

   LIBFOO_TYPE = 'script'

If no type is defined for a package, it will be considered a script-based
package. If applicable, loaded extensions may provide support for custom site
protocols.

Using a specific type will create a dependency for a project that the respective
host tool is installed on the host system. For example, if a CMake type is set,
the host system will need to have ``cmake`` installed on the system.

LIBFOO_VERSION
^^^^^^^^^^^^^^
.. |LIBFOO_VERSION| replace:: ``LIBFOO_VERSION``

The version of the package. Typically the version value should be formatted in a
semantic versioning style; however, it is up to the developer to decide the best
version value to use for a package. It is important to note that the version
value is used to determine build output folder names, cache files and more.

.. code-block:: python

   LIBFOO_VERSION = '1.0.0'

For some VCS types, the version value will be used to acquire a specific
revision of sources. If for some case the desired version value cannot be
gracefully defined (e.g. ``libfoo-v1.0`` will produce output directories such as
``libfoo-libfoo-v1.0``), |LIBFOO_REVISION|_ can be used.

See also |LIBFOO_DEVMODE_REVISION|_ and |LIBFOO_REVISION|_.

Advanced package configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following outlines more advanced configuration options available for
packages.

LIBFOO_BUILD_SUBDIR
^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_BUILD_SUBDIR| replace:: ``LIBFOO_BUILD_SUBDIR``

Sub-directory where a package's extracted sources holds its buildable content.
Sources for a package may be nested inside one or more directories. A package
can specify the sub-directory where the configuration, build and installation
processes are invoked from.

.. code-block:: python

   LIBFOO_BUILD_SUBDIR = 'subdir'

LIBFOO_DEVMODE_IGNORE_CACHE
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Flag value to explicitly indicate that a package should ignore any generated
cache file when operating in :ref:`development mode <development mode>`.
In most cases, users want to take advantage of cached sources to prevent
having to re-fetch the same content again between builds. However, some
packages may be configured in a way where their request for a package's
contents varies from a fresh stage. For example, when pulling from a
branch, releng-tool will not attempt to re-fetch from a site since a
cached content has already been fetched. If a developer configures a
package to use a revision value with dynamic content, they may wish to use
this option to have a user always force fetching new content from a
clean state.

.. code-block:: python

   LIBFOO_DEVMODE_IGNORE_CACHE = True

By default, this option is not defined and results can vary based off the site
type being fetched. In most cases, fetch operations will treat the default case
of this option as disabled (``False``). DVCS site types may elect to enable this
option by default (``True``) if the target revision is a branch.

LIBFOO_DEVMODE_REVISION
^^^^^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_DEVMODE_REVISION| replace:: ``LIBFOO_DEVMODE_REVISION``

Specifies a development revision for a package. When a project is being
built in :ref:`development mode <development mode>`, the development
revision is used over the configured |LIBFOO_REVISION|_ value. If a
development revision is not defined for a project, a package will still
use the configured |LIBFOO_REVISION|_ while in development mode.

.. code-block:: python

   LIBFOO_DEVMODE_REVISION = 'feature/alpha'

See also |LIBFOO_REVISION|_ and |LIBFOO_VERSION|_.

LIBFOO_EXTENSION
^^^^^^^^^^^^^^^^

Specifies a filename extension for the package. A package may be cached inside
the download directory to be used when the extraction phase is invoked.
releng-tool attempts to determine the most ideal extension for this cache file;
however some cases the detected extension may be incorrect. To deal with this
situation, a developer can explicitly specify the extension value using this
option.

.. code-block:: python

   LIBFOO_EXTENSION = 'tgz'

LIBFOO_EXTERNAL
^^^^^^^^^^^^^^^
.. |LIBFOO_EXTERNAL| replace:: ``LIBFOO_EXTERNAL``

Flag value to explicitly indicate that a package is an external package.
External packages will generate warnings if :ref:`hashes <hash_files>`, an
:ref:`ASCII-armor <ascii_armor>` or `licenses`_ are missing. By default,
packages are considered external unless explicitly configured to be internal.

.. code-block:: python

   LIBFOO_EXTERNAL = True

See also `internal and external packages`_.

LIBFOO_EXTOPT
^^^^^^^^^^^^^

Specifies extension-specific options. Packages wishing to take advantage of
extension-specific capabilities can forward options to extensions by defining a
dictionary of values.

.. code-block:: python

   LIBFOO_EXTOPT = {
       'option-a': True,
       'option-b': 'value',
   }

LIBFOO_EXTRACT_TYPE
^^^^^^^^^^^^^^^^^^^

Specifies a custom extraction type for a package. If a configured extension
supports a custom extraction capability, the registered extraction type can be
explicitly registered in this option.

.. code-block:: python

   LIBFOO_EXTRACT_TYPE = 'ext-custom-extract'

LIBFOO_FETCH_OPTS
^^^^^^^^^^^^^^^^^
.. |LIBFOO_FETCH_OPTS| replace:: ``LIBFOO_FETCH_OPTS``

Provides a means to pass command line options into the fetch process. This
option can be defined as a dictionary of string pairs or a list with strings --
either way defined will generate argument values which may be included in a
fetch event. This field is optional. Not all site types may support this
option.

.. code-block:: python

   LIBFOO_FETCH_OPTS = {
       # adds "--option value" to the command
       '--option': 'value',
   }

   # (or)

   LIBFOO_FETCH_OPTS = [
       # adds "--some-option" to the command
       '--some-option',
   ]

LIBFOO_FIXED_JOBS
^^^^^^^^^^^^^^^^^

Explicitly configure the total number of jobs a package can use. The primary use
case for this option is to help limit the total number of jobs for a package
that cannot support a large or any parallel build environment.

.. code-block:: python

   LIBFOO_FIXED_JOBS = 1

LIBFOO_GIT_CONFIG
^^^^^^^^^^^^^^^^^
.. |git-config| replace:: ``git config``

Apply additional repository-specific Git configuration settings (|git-config|_)
after a Git repository cache has been initialized. By default, no
repository-specific configurations are introduced (i.e. all Git calls will use
the global configuration set).

.. code-block:: python

   LIBFOO_GIT_CONFIG = {
      'core.example': 'value',
   }

LIBFOO_GIT_DEPTH
^^^^^^^^^^^^^^^^
.. |--depth| replace:: ``--depth``

Limit fetching for a Git-based source to the specified number of commits. The
value provided will be used with the |--depth|_ argument. By default, the depth
will be set to a value of ``1``. If a developer wishes use fetch all commits
from all refspecs, a developer can specify a value of ``0``.

While the default depth is a value of ``1``, an exception is made when the depth
is not explicitly set and the |LIBFOO_REVISION|_ value defined is a hash. For
this case, if the revision is not found with the implicitly-defined shallow
depth of ``1``, the entire history of the repository will be fetched.

.. code-block:: python

   LIBFOO_GIT_DEPTH = 0

See also |LIBFOO_GIT_REFSPECS|_ and :ref:`configuration quirks <quirks>`.

LIBFOO_GIT_REFSPECS
^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_GIT_REFSPECS| replace:: ``LIBFOO_GIT_REFSPECS``

List of addition refspecs to fetch when using a ``git`` VCS type. By default, a
Git fetch request will acquire all ``heads`` and ``tags`` refspecs. If a
developer wishes use revisions from different refspecs (for example, a pull
request), a developer can specify the additional refspecs to acquire when
fetching.

.. code-block:: python

   LIBFOO_GIT_REFSPECS = ['pull/*']

LIBFOO_GIT_SUBMODULES
^^^^^^^^^^^^^^^^^^^^^

Flag value to indicate whether or not a package's Git submodules should be
fetched/extracted during a package's own fetch/extraction stages. By default,
submodules are not fetched. Ideally, any dependencies for a package are
recommended to be defined in their own individual package; however, this may not
be ideal for all environments. When configured, submodules will be cached in the
same fashion as other Git-based packages. Note that submodule caching is
specific to the repository being processed (i.e. they cannot be "shared" between
other packages). If multiple packages have the same dependency defined through a
submodule, it is recommended to create a new package and reference its contents
instead.

.. code-block:: python

   LIBFOO_GIT_SUBMODULES = True

LIBFOO_GIT_VERIFY_REVISION
^^^^^^^^^^^^^^^^^^^^^^^^^^

Flag value to indicate whether or not the target revision is required to be
signed before it can be used. When this value is set, the configured revision
for a repository will not be extracted unless the GPG signature. This includes
if the public key for the author is not registered in the local system or if the
target revision is not signed.

.. code-block:: python

   LIBFOO_GIT_VERIFY_REVISION = True

LIBFOO_HOST_PROVIDES
^^^^^^^^^^^^^^^^^^^^
.. |LIBFOO_HOST_PROVIDES| replace:: ``LIBFOO_HOST_PROVIDES``

Hints at what host tools this package may be providing. A project may have a
series of prerequisites, which are checked at the start of a run. This is to
help ensure required host tools are available before attempting to build a
project. If a package is designed to provide a host package (e.g. when using
|LIBFOO_INSTALL_TYPE|_ with the ``host`` option), these packages can provide
tools other packages may rely on. However, prerequisites checks will occur
before these packages may be built, preventing a build from running. This
option allows a developer to hint at what tools a host package may provide.
By specifying the name of a tool in this option, an initial prerequisites
check will not fail if a tool is not available at the start of a run.

.. code-block:: python

   LIBFOO_HOST_PROVIDES = 'some-tool'

   # (or)

   LIBFOO_HOST_PROVIDES = [
       'tool-a',
       'tool-b',
       'tool-c',
   ]

See also |LIBFOO_INSTALL_TYPE|_.

LIBFOO_INTERNAL
^^^^^^^^^^^^^^^
.. |LIBFOO_INTERNAL| replace:: ``LIBFOO_INTERNAL``

Flag value to explicitly indicate that a package is an internal package.
Internal packages will not generate warnings if :ref:`hashes <hash_files>`, an
:ref:`ASCII-armor <ascii_armor>` or `licenses`_ are missing. When configured in
:ref:`local-sources mode <local-sources mode>`, package sources are searched
for in the local directory opposed to site fetched sources. By default,
packages are considered external unless explicitly configured to be internal.

.. code-block:: python

   LIBFOO_INTERNAL = True

See also `internal and external packages`_.

LIBFOO_NO_EXTRACTION
^^^^^^^^^^^^^^^^^^^^

.. warning::

   If ``LIBFOO_NO_EXTRACTION`` is configured for a package, the package cannot
   define additional :ref:`hashes <hash_files>`, configure an
   :ref:`ASCII-armor <ascii_armor>`, define a list of ``LIBFOO_LICENSE_FILES``
   to manage or expect to support various actions (such as building; since no
   sources are available).

Flag value to explicitly indicate that a package should not extract the package
contents. This feature is primarily used when using releng-tool to fetch content
for one or more packages (into ``DL_DIR``) to be used by another package the
releng-tool project defines.

.. code-block:: python

   LIBFOO_NO_EXTRACTION = True

Limitations exist when using the ``LIBFOO_NO_EXTRACTION`` option. Since
releng-tool will not be used to extract a package's archive (if any), hash
entries for files found inside the archive cannot be checked against. If any
files other than the archive itself is listed, releng-tool will stop processing
due to a hash check failure. In addition, since releng-tool does not have the
extracted contents of an archive, it is unable to acquire a copy of the
project's license file. Specifying ``LIBFOO_LICENSE_FILES`` for projects with
the no-extraction flag enabled will result in a warning. By default, this option
is disabled with a value of ``False``.

LIBFOO_PREFIX
^^^^^^^^^^^^^
.. |LIBFOO_PREFIX| replace:: ``LIBFOO_PREFIX``

Specifies the sysroot prefix value to use for the package. An explicitly
provided prefix value will override the project-defined or default sysroot
prefix value.

.. code-block:: python

   LIBFOO_PREFIX = '/usr'

See also |CONF_SYSROOT_PREFIX|_.

LIBFOO_REVISION
^^^^^^^^^^^^^^^
.. |LIBFOO_REVISION| replace:: ``LIBFOO_REVISION``

Specifies a revision value for a package. When a package fetches content using
source management tools, the revision value is used to determine which sources
should be acquired (e.g. a tag). If a revision is not defined package, a package
will use the configured |LIBFOO_VERSION|_.

.. code-block:: python

   LIBFOO_REVISION = 'libfoo-v2.1'

For users planning to take advantage of
:ref:`development mode <development mode>` capabilities, multiple revisions
can be configured based off the mode:

.. code-block:: python

   LIBFOO_REVISION = {
       DEFAULT_REVISION: 'libfoo-v2.1',
       'develop': 'main',
   }

See also |LIBFOO_DEVMODE_REVISION|_ and |LIBFOO_VERSION|_.

LIBFOO_SKIP_REMOTE_CONFIG
^^^^^^^^^^^^^^^^^^^^^^^^^

Flag value to explicitly indicate that a package should not attempt to load any
package configurations which may be defined in the package's source. A package,
by default, has the ability to load configuration information from a package's
source. If the package includes a ``.releng-tool`` file at the root of their
sources, supported configuration options that have not been populated will be
registered into the package before invoking a package's configuration stage.

.. code-block:: python

   LIBFOO_SKIP_REMOTE_CONFIG = True

See also :ref:`configuration quirks <quirks>`.

LIBFOO_SKIP_REMOTE_SCRIPTS
^^^^^^^^^^^^^^^^^^^^^^^^^^

Flag value to explicitly indicate that a package should not attempt to load any
package scripts which may be defined in the package's source. Typically, a
script-based package will load configuration, build, etc. scripts from its
package definition folder. If a script-based package is missing a stage script
to invoke and finds an associated script in the package's source, the detected
script will be invoked. For example, if ``libfoo`` package may attempt to load
a ``libfoo-configure`` script for a configuration stage. In the event that the
script cannot be found and remote scripting is permitted for a package, the
script (if exists) ``releng-configure`` will be loaded from the root of the
package's contents.

.. code-block:: python

   LIBFOO_SKIP_REMOTE_CONFIG = True

See also :ref:`configuration quirks <quirks>`.

LIBFOO_STRIP_COUNT
^^^^^^^^^^^^^^^^^^

Specifies the strip count to use when attempting to extract sources from an
archive. By default, the extraction process will strip a single directory from
an archive (value: 1). If a package's archive has no container directory, a
strip count of zero can be set; likewise if an archive contains multiple
container directories, a higher strip count can be set.

.. code-block:: python

   LIBFOO_STRIP_COUNT = 1

LIBFOO_VCS_TYPE
^^^^^^^^^^^^^^^
.. |LIBFOO_VCS_TYPE| replace:: ``LIBFOO_VCS_TYPE``

Explicitly sets the version control system type to use when acquiring sources.
releng-tool attempts to automatically determine the VCS type of a package based
off a |LIBFOO_SITE|_ value. In some scenarios, a site value may be unable to
specify a desired prefix/postfix. A developer can instead explicitly set the VCS
type to be used no matter what the site value is configured as.

Supported types are as follows:

- ``bzr`` (Bazaar)
- ``cvs`` (CVS)
- ``git`` (Git)
- ``hg``  (Mercurial)
- ``local`` (no VCS; local interim-development package)
- ``none`` (no VCS; virtual package)
- ``rsync`` (rsync)
- ``scp`` (SCP)
- ``svn`` (SVN)
- ``url`` (URL)

.. code-block:: python

   LIBFOO_VCS_TYPE = 'git'

If a project registers a custom extension which provides a custom VCS type, the
extension type can be set in this option.

For users planning to take advantage of
:ref:`development mode <development mode>` capabilities with mode-specific
sites, users can provide an explicit VCS type based off a configured mode:

.. code-block:: python

   LIBFOO_VCS_TYPE = {
       DEFAULT_REVISION: 'git',
       'legacy': 'cvs',
   }

Using a specific type will create a dependency for a project that the respective
host tool is installed on the host system. For example, if a Git VCS-type is
set, the host system will need to have ``git`` installed on the system.

Note that the ``local`` type is designed to be a special/development-helper type
only. When set, this option allows placing the contents of a module directly
inside the definition folder (alongside the definition file). This approach is
similar to using :ref:`local-sources mode <local-sources mode>` where it avoids
the need to have the module content located in a site to be fetched --
specifically, for initial development/testing/training scenarios. It is never
recommended to store the package's "main content" inside a releng-tool project,
thus using the ``local`` type will always generate a warning message.

.. _package_bootstrapping_and_postprocessing:

Package bootstrapping and post-processing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every package, no matter which package |LIBFOO_TYPE|_ is defined, can create a
bootstrapping or post-processing script to invoke before a package starts a
configuration stage or after a package has completed an installation stage,
respectively.

The existence of a ``<package>-bootstrap`` inside a package directory will
trigger the bootstrapping stage for the package. An example bootstrapping script
(``libfoo-bootstrap``) can be as follows:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   print('perform bootstrapping work')

The existence of a ``<package>-post`` inside a package directory will
trigger the post-processing stage for the package. An example post-processing
script (``libfoo-post``) can be as follows:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   print('perform post-processing work')

Bootstrapping or post-processing scripts for a package are optional; thus, if no
scripts are provided for a package, no bootstrapping or post-processing will be
performed for the package.

See also `script helpers`_ for helper functions/variables available for use.

.. include:: developer-guide/packages-sites
.. include:: developer-guide/packages-hashes
.. include:: developer-guide/packages-ascii-armor
.. include:: developer-guide/packages-type-script
.. include:: developer-guide/packages-type-autotools
.. include:: developer-guide/packages-type-cmake
.. include:: developer-guide/packages-type-make
.. include:: developer-guide/packages-type-python
.. include:: developer-guide/packages-type-scons

.. _--depth: https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---depthltdepthgt
.. _git-config: https://git-scm.com/docs/git-config
