SiegfriedSiegert/PTU5KAS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update userguide to commit/branch, dropping refspec

Browse Source 
Dropping all refspec references shall help new users on the right path
from the beginning.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
This commit is contained in:
Jan Kiszka 2023-05-30 14:05:59 +02:00
parent 716937b028
commit 578666766c
1 changed files with 23 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/userguide.rst
View File

@ -138,7 +138,7 @@ arguably easier to read, this documentation focuses on the YAML format.
# bblayers.conf: # bblayers.conf:
poky: poky:
url: "https://git.yoctoproject.org/git/poky" url: "https://git.yoctoproject.org/git/poky"
refspec: 89e6c98d92887913cadf06b2adb97f26cde4849b commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers: layers:
meta: meta:
meta-poky: meta-poky:
@ -218,7 +218,7 @@ It's also possible to include configuration files from other repos like this:
meta-custom: meta-custom:
meta-bsp-collection: meta-bsp-collection:
url: "https://www.example.com/git/meta-bsp-collection" url: "https://www.example.com/git/meta-bsp-collection"
refspec: 3f786850e387550fdab836ed7e6dc881de23001b commit: 3f786850e387550fdab836ed7e6dc881de23001b
layers: layers:
# Additional to the layers that are added from this repository # Additional to the layers that are added from this repository
# in the hw1/kas-hw-bsp1.yml, we add here an additional bsp # in the hw1/kas-hw-bsp1.yml, we add here an additional bsp
@ -226,7 +226,7 @@ It's also possible to include configuration files from other repos like this:
meta-custom-bsp: meta-custom-bsp:
poky: poky:
url: "https://git.yoctoproject.org/git/poky" url: "https://git.yoctoproject.org/git/poky"
refspec: 89e6c98d92887913cadf06b2adb97f26cde4849b commit: 89e6c98d92887913cadf06b2adb97f26cde4849b
layers: layers:
# If `kas-poky.yml` adds the `meta-yocto-bsp` layer and we # If `kas-poky.yml` adds the `meta-yocto-bsp` layer and we
# do not want it in our bblayers for this project, we can # do not want it in our bblayers for this project, we can
@ -276,8 +276,8 @@ configuration flaws that can easily emerge from them.
Working with lockfiles Working with lockfiles
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
KAS supports the use of lockfiles to pinpoint repositories to exact refspecs KAS supports the use of lockfiles to pinpoint repositories to exact commit ID
(e.g. SHA-1 refs for git). A lockfile hereby only overrides the refspecs (e.g. SHA-1 refs for git). A lockfile hereby only overrides the commit ID
defined in a kas file. When performing the checkout operation (or any other defined in a kas file. When performing the checkout operation (or any other
operation that performs a checkout), kas checks if a file named operation that performs a checkout), kas checks if a file named
``<filename>.lock.<ext>`` is found next to the first file stated on the kas ``<filename>.lock.<ext>`` is found next to the first file stated on the kas
@ -295,7 +295,7 @@ and its corresponding lockfile ``kas/kas-isar.lock.yml``.
repos: repos:
isar: isar:
url: https://github.com/ilbers/isar.git url: https://github.com/ilbers/isar.git
refspec: next branch: next
``kas/kas-isar.lock.yml``: ``kas/kas-isar.lock.yml``:
@ -306,7 +306,7 @@ and its corresponding lockfile ``kas/kas-isar.lock.yml``.
overrides: overrides:
repos: repos:
isar: isar:
refspec: 0336610df8bb0adce76ef8c5a921c758efed9f45 commit: 0336610df8bb0adce76ef8c5a921c758efed9f45
The ``dump`` plugin provides helpers to simplify the creation and update The ``dump`` plugin provides helpers to simplify the creation and update
of lockfiles. For details, see the plugins documentation: :mod:`kas.plugins.dump`. of lockfiles. For details, see the plugins documentation: :mod:`kas.plugins.dump`.
@ -357,7 +357,7 @@ Configuration reference
* ``defaults``: dict [optional] * ``defaults``: dict [optional]
This key can be used to set default values for various properties. This key can be used to set default values for various properties.
This may help you to avoid repeating the same property assignment in This may help you to avoid repeating the same property assignment in
multiple places if, for example, you wish to use the same refspec for multiple places if, for example, you wish to use the same branch for
all repositories. all repositories.
* ``repos``: dict [optional] * ``repos``: dict [optional]
@ -366,8 +366,8 @@ Configuration reference
overridden by setting the same property to a different value in a given overridden by setting the same property to a different value in a given
repository. repository.
* ``refspec``: string [optional] * ``branch``: string [optional]
Sets the default ``refspec`` property applied to all repositories that Sets the default ``branch`` property applied to all repositories that
do not override this. do not override this.
* ``patches``: dict [optional] * ``patches``: dict [optional]
@ -433,10 +433,15 @@ Configuration reference
The type of version control repository. The default value is ``git`` The type of version control repository. The default value is ``git``
and ``hg`` is also supported. and ``hg`` is also supported.
* ``refspec``: string [optional] * ``commit``: string [optional]
The refspec that should be used. If ``url`` was specified but no The commit ID (branch names, no symbolic refs, no tags) that should be
``refspec`` the revision you get depends on the defaults of the version used. If ``url`` was specified but no ``commit`` and no ``branch``, the
control system used. revision you get depends on the defaults of the version control system
used.
* ``branch``: string [optional]
The upstream branch that should be tracked. If no ``commit`` was
specified, the head of the upstream is checked out.
* ``path``: string [optional] * ``path``: string [optional]
The path where the repository is stored. The path where the repository is stored.
@ -462,7 +467,7 @@ Configuration reference
meta-foo: meta-foo:
url: https://github.com/bar/meta-foo.git url: https://github.com/bar/meta-foo.git
path: layers/meta-foo path: layers/meta-foo
refspec: master branch: master
layers: layers:
.: .:
contrib: contrib:
@ -505,9 +510,9 @@ Configuration reference
* ``<repo-id>``: dict [optional] * ``<repo-id>``: dict [optional]
Mapps to the ``<repo-id>`` entry. Mapps to the ``<repo-id>`` entry.
* ``refspec``: string [optional] * ``commit``: string [optional]
Pinned refspec which overrides the ``refspec`` of the corresponding Pinned commit ID which overrides the ``commit`` of the corresponding
repo. This refspec must be resolved (i.e. no branch or tag name). repo.
* ``bblayers_conf_header``: dict [optional] * ``bblayers_conf_header``: dict [optional]
This contains strings that should be added to the ``bblayers.conf`` before This contains strings that should be added to the ``bblayers.conf`` before