# git plugin

## git - stage files from a git repository

Host dependencies:

> - git

Attention

Note that this plugin will checkout git submodules by default; even if they are not specified in the .bst file.

Usage:

    # Specify the git source kind
    kind: git

    # Specify the repository url, using an alias defined
    # in your project configuration is recommended.
    url: upstream:foo.git

    # Optionally specify a symbolic tracking branch or tag, this
    # will be used to update the 'ref' when refreshing the pipeline.
    track: master

    # Optionally specify the ref format used for tracking.
    # The default is 'sha1' for the raw commit hash.
    # If you specify 'git-describe', the commit hash will be prefixed
    # with the closest tag.
    ref-format: sha1

    # Specify the commit ref, this must be specified in order to
    # checkout sources and build, but can be automatically updated
    # if the 'track' attribute was specified.
    ref: d63cbb6fdc0bbdadc4a1b92284826a6d63a7ebcd

    # Optionally specify whether submodules should be checked-out.
    # This is done recursively, as with `git clone --recurse-submodules`.
    # If not set, this will default to 'True'
    checkout-submodules: True

    # If your repository has submodules, explicitly specifying the
    # url from which they are to be fetched allows you to easily
    # rebuild the same sources from a different location. This is
    # especially handy when used with project defined aliases which
    # can be redefined at a later time, or overridden with mirrors.
    #
    # You may also explicitly specify whether to check out this
    # submodule. If 'checkout' is set, it will control whether to
    # checkout that submodule and recurse into it. It defaults to the
    # value of 'checkout-submodules'.
    submodules:
      plugins/bar:
        url: upstream:bar.git
        checkout: True
      plugins/bar/quux:
        checkout: False
      plugins/baz:
        url: upstream:baz.git
        checkout: False

    # Modify the default version guessing pattern
    #
    # Since 2.5
    #
    version-guess-pattern: '(\d+)\.(\d+)(?:\.(\d+))?'

    # Override the version guessing with an explicit version
    #
    # Since 2.5
    #
    version: 5.9

    # Enable tag tracking.
    #
    # This causes the `tags` metadata to be populated automatically
    # as a result of tracking the git source.
    #
    # By default this is 'False'.
    #
    track-tags: True

    # If the list of tags below is set, then a lightweight dummy
    # git repository will be staged along with the content at
    # build time.
    #
    # This is useful for a growing number of modules which use
    # `git describe` at build time in order to determine the version
    # which will be encoded into the built software.
    #
    # The 'tags' below is considered as a part of the git source
    # reference and will be stored in the 'project.refs' file if
    # that has been selected as your project's ref-storage.
    #
    # Migration notes:
    #
    #   If you are upgrading from BuildStream 1.2, which used to
    #   stage the entire repository by default, you will notice that
    #   some modules which use `git describe` are broken, and will
    #   need to enable this feature in order to fix them.
    #
    #   If you need to enable this feature without changing the
    #   the specific commit that you are building, then we recommend
    #   the following migration steps for any git sources where
    #   `git describe` is required:
    #
    #     o Enable `track-tags` feature
    #     o Set the `track` parameter to the desired commit sha which
    #       the current `ref` points to
    #     o Run `bst source track` for these elements, this will result in
    #       populating the `tags` portion of the refs without changing
    #       the refs
    #     o Restore the `track` parameter to the branches which you have
    #       previously been tracking afterwards.
    #
    tags:
    - tag: lightweight-example
      commit: 04ad0dc656cb7cc6feb781aa13bdbf1d67d0af78
      annotated: false
    - tag: annotated-example
      commit: 10abe77fe8d77385d86f225b503d9185f4ef7f3a
      annotated: true

See built-in functionality doumentation for details on common configuration options for sources.

### Configurable Warnings:

This plugin provides the following configurable warnings:

- `git:inconsistent-submodule` - A submodule present in the git repository’s .gitmodules was never added with git submodule add.

- `git:unlisted-submodule` - A submodule is present in the git repository but was not specified in the source configuration and was not disabled for checkout.

- `git:invalid-submodule` - A submodule is specified in the source configuration but does not exist in the repository.

This plugin also utilises the following configurable core warnings:

- ref-not-in-track - The provided ref was not found in the provided track in the element’s git repository.

### Reporting SourceInfo

The git source reports the URL of the git repository as the url.

Further, the git source reports the SourceInfoMedium.GIT medium and the SourceVersionType.COMMIT version_type, for which it reports the git commit sha as the version.

If the ref is found to be in `git-describe` format, an attempt to guess the version based on the git tag portion of the ref will be made for the reporting of the guess_version. Control over how the guess is made or overridden is controlled based on the `version-guess-pattern` and `version` configuration attributes described above.

In order to understand how the `version-guess-pattern` works, please refer to the documentation for utils.guess_version()

In the case that a git describe string represents a commit that is beyond the tag portion of the git describe reference (i.e. the version is not exact), then the number of commits found beyond the tag will be reported in the `commit-offset` field of the extra_data.

Attention

SourceInfo is not reported for submodules.

This is due to the limitation that the git plugin requires to have the toplevel module fetched first in order to have knowledge of the commits of the submodules.

While this does not provide complete information on the provenance of sources, at least one can consider the module to be a comprehensive whole, and the versions of submodules are deterministically controlled by the version of the main repository.