111 lines
3.2 KiB
ReStructuredText
111 lines
3.2 KiB
ReStructuredText
:title: Zuul Cloner
|
|
|
|
Zuul Cloner
|
|
===========
|
|
|
|
Zuul includes a simple command line client that may be used to clone
|
|
repositories with Zuul references applied.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
Clone map
|
|
'''''''''
|
|
|
|
By default, Zuul cloner will clone the project under ``basepath`` which
|
|
would create sub directories whenever a project name contains slashes. Since
|
|
you might want to finely tweak the final destination, a clone map lets you
|
|
change the destination on a per project basis. The configuration is done using
|
|
a YAML file passed with ``-m``.
|
|
|
|
With a project hierarchy such as::
|
|
|
|
project
|
|
thirdparty/plugins/plugin1
|
|
|
|
You might want to get ``project`` straight in the base path, the clone map would be::
|
|
|
|
clonemap:
|
|
- name: 'project'
|
|
dest: '.'
|
|
|
|
Then to strip out ``thirdparty`` such that the plugins land under the
|
|
``/plugins`` directory of the basepath, you can use regex and capturing
|
|
groups::
|
|
|
|
clonemap:
|
|
- name: 'project'
|
|
dest: '.'
|
|
- name: 'thirdparty/(plugins/.*)'
|
|
dest: '\1'
|
|
|
|
The resulting workspace will contains::
|
|
|
|
project -> ./
|
|
thirdparty/plugins/plugin1 -> ./plugins/plugin1
|
|
|
|
|
|
Zuul parameters
|
|
'''''''''''''''
|
|
|
|
The Zuul cloner reuses Zuul parameters such as ZUUL_BRANCH, ZUUL_REF or
|
|
ZUUL_PROJECT. It will attempt to load them from the environment variables or
|
|
you can pass them as parameters (in which case it will override the
|
|
environment variable if it is set). The matching command line parameters use
|
|
the ``zuul`` prefix hence ZUUL_REF can be passed to the cloner using
|
|
``--zuul-ref``.
|
|
|
|
Usage
|
|
-----
|
|
The general options that apply are:
|
|
|
|
.. program-output:: zuul-cloner --help
|
|
|
|
|
|
Ref lookup order
|
|
''''''''''''''''
|
|
|
|
The Zuul cloner will attempt to lookup references in this order:
|
|
|
|
1) Zuul reference for the indicated branch
|
|
2) Zuul reference for the master branch
|
|
3) The tip of the indicated branch
|
|
4) The tip of the master branch
|
|
|
|
The "indicated branch" is one of the following:
|
|
|
|
A) The project-specific override branch (from project_branches arg)
|
|
B) The user specified branch (from the branch arg)
|
|
C) ZUUL_BRANCH (from the zuul_branch arg)
|
|
|
|
Clone order
|
|
-----------
|
|
|
|
When cloning repositories, the destination folder should not exist or
|
|
``git clone`` will complain. This happens whenever cloning a sub project
|
|
before its parent project. For example::
|
|
|
|
zuul-cloner project/plugins/plugin1 project
|
|
|
|
Will create the directory ``project`` when cloning the plugin. The
|
|
cloner processes the clones in the order supplied, so you should swap the
|
|
projects::
|
|
|
|
zuul-cloner project project/plugins/plugin1
|
|
|
|
Cached repositories
|
|
-------------------
|
|
|
|
The ``--cache-dir`` option can be used to reduce network traffic by
|
|
cloning from a local repository which may not be up to date.
|
|
|
|
If the ``--cache-dir`` option is supplied, zuul-cloner will start by
|
|
cloning any projects it processes from those found in that directory.
|
|
The URL of origin remote of the resulting clone will be reset to use
|
|
the ``git_base_url`` and then the remote will be updated so that the
|
|
repository has all the information in the upstream repository.
|
|
|
|
The default for ``--cache-dir`` is taken from the environment variable
|
|
``ZUUL_CACHE_DIR``. A value provided explicitly on the command line
|
|
overrides the environment variable setting.
|