1Repo Pull
2=========
3
4`repo_pull.py` pulls multiple change lists from a Gerrit code review website.
5A user may specify a query string and `repo_pull.py` will pull the matching
6change lists.
7
8For example, to pull the `repo-pull-initial-cl` topic from AOSP, run this
9command:
10
11    repo_pull.py pull 'topic:repo-pull-initial-cl' \
12        -g https://android-review.googlesource.com
13
14Read [Usage](#Usages) and [Examples](#Examples) for more details.
15
16
17## Installation
18
19`repo_pull.py` requires `.gitcookies` to access Gerrit APIs.  Please
20check whether the Gerrit Code Review URL is in `~/.gitcookies`.
21
22If you don't have an entry, follow these steps:
23
241. Visit the [Gerrit Code Review](https://android-review.googlesource.com).
25
262. Click [Settings -> HTTP Credentials](https://android-review.googlesource.com/settings/#HTTPCredentials)
27
283. Click **Obtain password**
29
304. Copy the highlighted shell commands and paste them in a terminal.
31
32Note: You must repeat these for each Gerrit Code Review websites.
33
34Note: For Googlers, please read go/repo-pull-for-google for details.
35
36
37## Usages
38
39Command line usages:
40
41    $ repo_pull.py [sub-command] [query] \
42                   [-g gerrit] \
43                   [-b local-topic-branch] \
44                   [-j num-threads] \
45                   [--limits max-num-changes]
46
47
48Three sub-commands are supported:
49
50* `repo_pull.py json` prints the change lists in the JSON file format.
51
52* `repo_pull.py bash` prints the *bash commands* that can pull the change lists.
53
54* `repo_pull.py pull` *pulls the change lists* immediately.
55
56
57### Query String
58
59`[query]` is the query string that can be entered to the Gerrit search box.
60
61These are common queries:
62
63* `topic:name`
64* `hashtag:name`
65* `branch:name`
66* `project:name`
67* `owner:name`
68* `is:open` | `is:merged` | `is:abandoned`
69* `message:text`
70
71
72### Options
73
74* `-g` or `--gerrit` specifies the URL of the Gerrit Code Review website.
75
76* `-b` or `--branch` specifies the local branch name that will be passed to
77  `repo start`.
78
79* `-j` or `--parallel` specifies the number of parallel threads while pulling
80  change lists.
81
82* `-n` or `--limits` specifies the maximum number of change lists.  (default:
83  1000)
84
85* `-m` or `--merge` specifies the method to pick the merge commits.  (default:
86  `merge-ff-only`)
87
88* `-p` or `--pick` specifies the method to pick the non-merge commits.
89  (default: `pick`)
90
91  * `pick` maps to `git cherry-pick --allow-empty`
92  * `merge` maps to `git merge --no-edit`
93  * `merge-ff-only` maps to `git merge --no-edit --ff-only`
94  * `merge-no-ff` maps to `git merge --no-edit --no-ff`
95  * `reset` maps to `git reset --hard`
96  * `checkout` maps to `git checkout`
97
98
99## Examples
100
101To print the change lists with the topic `repo-pull-initial-cl` in JSON file
102format:
103
104```
105repo_pull.py json 'topic:repo-pull-initial-cl' \
106    -g https://android-review.googlesource.com
107```
108
109To print the bash commands that can pull the change lists, use the `bash`
110command:
111
112```
113repo_pull.py bash 'topic:repo-pull-initial-cl' \
114    -g https://android-review.googlesource.com \
115    -b my-local-topic-branch
116```
117
118To pull the change lists immediately, use the `pull` command:
119
120```
121repo_pull.py pull 'topic:repo-pull-initial-cl' \
122    -g https://android-review.googlesource.com \
123    -b my-local-topic-branch
124```
125