git - stage files from a git repository¶
Note that this plugin will checkout git submodules by default; even if they are not specified in the .bst file.
# 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. # 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. # You may also explicitly specify whether to check out this # submodule. If 'checkout' is set, it will override # 'checkout-submodules' with the value set below. submodules: plugins/bar: url: upstream:bar.git checkout: True plugins/baz: url: upstream:baz.git checkout: False # 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.
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:unlisted-submodulewarning is available since format version 20
git:invalid-submodule- A submodule is specified in the source configuration but does not exist in the repository.
git:invalid-submodulewarning is available since format version 20
This plugin also utilises the following configurable
ref-not-in-track- The provided ref was not found in the provided track in the element’s git repository.