blob: bb33f828ef56570fc18ebbc2660546b48b65bbef [file] [log] [blame]
Antoine Musso45dd2cb2014-01-29 17:17:43 +01001:title: Zuul Cloner
2
3Zuul Cloner
4===========
5
6Zuul includes a simple command line client that may be used to clone
7repositories with Zuul references applied.
8
9Configuration
10-------------
11
12Clone map
13'''''''''
14
15By default, Zuul cloner will clone the project under ``basepath`` which
16would create sub directories whenever a project name contains slashes. Since
17you might want to finely tweak the final destination, a clone map lets you
18change the destination on a per project basis. The configuration is done using
19a YAML file passed with ``-m``.
20
21With a project hierarchy such as::
22
23 project
24 thirdparty/plugins/plugin1
25
26You might want to get ``project`` straight in the base path, the clone map would be::
27
28 clonemap:
29 - name: 'project'
30 dest: '.'
31
32Then to strip out ``thirdparty`` such that the plugins land under the
33``/plugins`` directory of the basepath, you can use regex and capturing
34groups::
35
36 clonemap:
37 - name: 'project'
38 dest: '.'
39 - name: 'thirdparty/(plugins/.*)'
40 dest: '\1'
41
42The resulting workspace will contains::
43
44 project -> ./
45 thirdparty/plugins/plugin1 -> ./plugins/plugin1
46
47
48Zuul parameters
49'''''''''''''''
50
51The Zuul cloner reuses Zuul parameters such as ZUUL_BRANCH, ZUUL_REF or
52ZUUL_PROJECT. It will attempt to load them from the environment variables or
53you can pass them as parameters (in which case it will override the
54environment variable if it is set). The matching command line parameters use
55the ``zuul`` prefix hence ZUUL_REF can be passed to the cloner using
56``--zuul-ref``.
57
58Usage
59-----
60The general options that apply are:
61
62.. program-output:: zuul-cloner --help
63
64Clone order
65-----------
66
67When cloning repositories, the destination folder should not exist or
68``git clone`` will complain. This happens whenever cloning a sub project
69before its parent project. For example::
70
71 zuul-cloner project/plugins/plugin1 project
72
73Will create the directory ``project`` when cloning the plugin. The
74cloner processes the clones in the order supplied, so you should swap the
75projects::
76
77 zuul-cloner project project/plugins/plugin1