[buildstream] 12/13: sources/git.py: Document tracking latest tag

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

root pushed a commit to branch tmewett/merge-git-tag
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit ad9cfda2a045ffeecffdb2807f0c4a4877917459
Author: Tom Mewett <to...@codethink.co.uk>
AuthorDate: Tue Jan 14 11:27:07 2020 +0000

    sources/git.py: Document tracking latest tag
---
 src/buildstream/plugins/sources/git.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/buildstream/plugins/sources/git.py b/src/buildstream/plugins/sources/git.py
index ce69895..e18f136 100644
--- a/src/buildstream/plugins/sources/git.py
+++ b/src/buildstream/plugins/sources/git.py
@@ -50,6 +50,20 @@ git - stage files from a git repository
    #
    track: master
 
+   # Optionally specify whether to instead choose the latest tagged commit
+   # when tracking. If a tracking revision has no tags, it is ignored.
+   #
+   # This option can either be True/False or a mapping with the optional keys
+   # 'match' and 'exclude'. These sub-options provide a list of glob expressions
+   # to filter which tags are considered when tracking. All tags matching one
+   # or more 'match' patterns and zero 'exclude' patterns are considered.
+   #
+   track-latest-tag:
+      match:
+         - v1.*
+      exclude:
+         - v1.4-pre*
+
    # 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
@@ -142,6 +156,9 @@ details on common configuration options for sources.
 
 This plugin provides the following :ref:`configurable warnings <configurable_warnings>`:
 
+- ``git:tag-not-found`` - 'track-latest-tag' is enabled but one or more
+  tracking targets has no matching tags in its history.
+
 - ``git:inconsistent-submodule`` - A submodule present in the git repository's .gitmodules was never
   added with `git submodule add`.