1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
#
# Copyright (C) 2016 Codethink Limited
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library. If not, see <http://www.gnu.org/licenses/>.
#
# Authors:
# Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
"""
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:**
.. code:: yaml
# 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.
# 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
# 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 :ref:`built-in functionality doumentation <core_source_builtins>` for
details on common configuration options for sources.
**Configurable Warnings:**
This plugin provides the following :ref:`configurable warnings <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.
.. note::
The ``git:unlisted-submodule`` warning is available since :ref:`format version 20 <project_format_version>`
- ``git:invalid-submodule`` - A submodule is specified in the source configuration but does not exist
in the repository.
.. note::
The ``git:invalid-submodule`` warning is available since :ref:`format version 20 <project_format_version>`
This plugin also utilises the following configurable :class:`core warnings <buildstream.types.CoreWarnings>`:
- :attr:`ref-not-in-track <buildstream.types.CoreWarnings.REF_NOT_IN_TRACK>` - The provided ref was not
found in the provided track in the element's git repository.
"""
from buildstream import _GitSourceBase
class GitSource(_GitSourceBase):
pass
# Plugin entry point
def setup():
return GitSource
|
