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