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:

usage: zuul-cloner [-h] [-m CLONE_MAP_FILE] [--workspace WORKSPACE] [-v]
                   [--color] [--version] [--cache-dir CACHE_DIR]
                   [--branch BRANCH] [--project-branch PROJECT=BRANCH]
                   [--zuul-branch $ZUUL_BRANCH] [--zuul-ref $ZUUL_REF]
                   [--zuul-url $ZUUL_URL] [--zuul-project $ZUUL_PROJECT]
                   [--zuul-newrev $ZUUL_NEWREV]
                   git_base_url projects [projects ...]

Zuul Project Gating System Cloner.

positional arguments:
  git_base_url          reference repo to clone from
  projects              list of Gerrit projects to clone

optional arguments:
  -h, --help            show this help message and exit
  -m CLONE_MAP_FILE, --map CLONE_MAP_FILE
                        specifiy clone map file
  --workspace WORKSPACE
                        where to clone repositories too
  -v, --verbose         verbose output
  --color               use color output
  --version             show zuul version
  --cache-dir CACHE_DIR
                        a directory that holds cached copies of repos from
                        which to make an initial clone. Can also be set via
                        ZUUL_CACHE_DIR environment variable.

project tuning:
  --branch BRANCH       branch to checkout instead of Zuul selected branch,
                        for example to specify an alternate branch to test
                        client library compatibility.
  --project-branch PROJECT=BRANCH
                        project-specific branch to checkout which takes
                        precedence over --branch if it is provided; may be
                        specified multiple times.

zuul environment:
  Let you override $ZUUL_* environment variables.

  --zuul-branch $ZUUL_BRANCH
  --zuul-ref $ZUUL_REF
  --zuul-url $ZUUL_URL
  --zuul-project $ZUUL_PROJECT
  --zuul-newrev $ZUUL_NEWREV

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:

1. The project-specific override branch (from project_branches arg)
2. The user specified branch (from the branch arg)
3. 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.