blob: b92a89d2f4cc9c1ac1cba1b02e1e07bf880529ed [file] [log] [blame]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001= Gerrit Code Review - Command Line Tools
Shawn O. Pearce4016a932009-05-28 15:12:40 -07002
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08003== Client
Shawn O. Pearce1f8d0a22009-06-15 18:31:12 -07004
Shawn O. Pearce3e4e8042010-01-29 12:48:21 -08005Client commands and hooks can be downloaded via scp, wget or curl
6from Gerrit's daemon, and then executed on the client system.
Shawn O. Pearceb89e1de2009-08-22 13:31:11 -07007
Shawn O. Pearce3e4e8042010-01-29 12:48:21 -08008To download a client command or hook, use scp or an http client:
Shawn O. Pearceb89e1de2009-08-22 13:31:11 -07009
Michael Ochmannb99feab2016-07-06 14:10:22 +020010----
David Shevitz013d3cb2018-09-21 15:25:45 -070011$ scp -p -P 29418 john.doe@review.example.com:bin/gerrit-cherry-pick ~/bin/
12$ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg .git/hooks/
Shawn O. Pearceb89e1de2009-08-22 13:31:11 -070013
David Shevitz013d3cb2018-09-21 15:25:45 -070014$ curl -Lo ~/bin/gerrit-cherry-pick http://review.example.com/tools/bin/gerrit-cherry-pick
15$ curl -Lo .git/hooks/commit-msg http://review.example.com/tools/hooks/commit-msg
Michael Ochmannb99feab2016-07-06 14:10:22 +020016----
Shawn O. Pearce3e4e8042010-01-29 12:48:21 -080017
Shawn O. Pearceb89e1de2009-08-22 13:31:11 -070018For more details on how to determine the correct SSH port number,
19see link:user-upload.html#test_ssh[Testing Your SSH Connection].
20
Edwin Kempincf830d52018-08-29 08:36:08 +020021[[client_commands]]
22=== Commands
Shawn O. Pearce1f8d0a22009-06-15 18:31:12 -070023
24link:cmd-cherry-pick.html[gerrit-cherry-pick]::
David Pursehouse4fd86432015-01-09 10:43:58 +090025 Download and cherry-pick one or more changes (commits).
Shawn O. Pearce1f8d0a22009-06-15 18:31:12 -070026
Edwin Kempincf830d52018-08-29 08:36:08 +020027[[client_hooks]]
28=== Hooks
Shawn O. Pearce1f8d0a22009-06-15 18:31:12 -070029
Shawn O. Pearceb89e1de2009-08-22 13:31:11 -070030Client hooks can be installed into a local Git repository, improving
31the developer experience when working with a Gerrit Code Review
32server.
Shawn O. Pearcebb2b5672009-08-21 18:33:10 -070033
34link:cmd-hook-commit-msg.html[commit-msg]::
David Shevitz013d3cb2018-09-21 15:25:45 -070035 Automatically generate `Change-Id:` tags in commit messages.
Shawn O. Pearcebb2b5672009-08-21 18:33:10 -070036
Shawn O. Pearcebb2b5672009-08-21 18:33:10 -070037
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080038== Server
Shawn O. Pearce4016a932009-05-28 15:12:40 -070039
40Aside from the standard Git server side actions, Gerrit supports
41several other commands over its internal SSH daemon. As Gerrit does
42not provide an interactive shell, the commands must be triggered
43from an ssh client, for example:
44
Michael Ochmannb99feab2016-07-06 14:10:22 +020045----
Shawn O. Pearce4016a932009-05-28 15:12:40 -070046 $ ssh -p 29418 review.example.com gerrit ls-projects
Michael Ochmannb99feab2016-07-06 14:10:22 +020047----
Shawn O. Pearce4016a932009-05-28 15:12:40 -070048
49For more details on how to determine the correct SSH port number,
50see link:user-upload.html#test_ssh[Testing Your SSH Connection].
51
Edwin Kempincf830d52018-08-29 08:36:08 +020052[[user_commands]]
53=== User Commands
Shawn O. Pearce4016a932009-05-28 15:12:40 -070054
David Ostrovsky1f04bca2013-10-19 10:38:50 +020055link:cmd-apropos.html[gerrit apropos]::
56 Search Gerrit documentation index.
57
Edwin Kempinf485a0d2012-03-30 08:11:47 +020058link:cmd-ban-commit.html[gerrit ban-commit]::
59 Bans a commit from a project's repository.
60
JouYoung Suhf29554a2022-04-07 17:00:29 -040061link:cmd-check-project-access.html[gerrit check-project-access]::
62 Check if user(s) can read non-config refs of a project
63
Hugo Arès169cb232015-01-08 15:40:06 -050064link:cmd-create-branch.html[gerrit create-branch]::
65 Create a new project branch.
66
Edwin Kempincf6c3592011-09-01 15:55:15 +020067link:cmd-ls-groups.html[gerrit ls-groups]::
68 List groups visible to the caller.
69
James Ring8e342722013-05-01 01:40:53 -070070link:cmd-ls-members.html[gerrit ls-members]::
71 List the membership of a group visible to the caller.
72
Shawn O. Pearce47769242011-06-14 16:40:48 -070073link:cmd-ls-projects.html[gerrit ls-projects]::
74 List projects visible to the caller.
75
76link:cmd-query.html[gerrit query]::
Dave Borowitzada289c2018-12-18 13:24:14 -080077 Query the change search index.
Shawn O. Pearce47769242011-06-14 16:40:48 -070078
79'gerrit receive-pack'::
Edwin Kempinf1acbb82011-09-15 12:49:42 +020080 'Deprecated alias for `git receive-pack`.'
Shawn O. Pearce47769242011-06-14 16:40:48 -070081
Hugo Arès169cb232015-01-08 15:40:06 -050082link:cmd-rename-group.html[gerrit rename-group]::
83 Rename an account group.
84
Shawn O. Pearce47769242011-06-14 16:40:48 -070085link:cmd-review.html[gerrit review]::
86 Verify, approve and/or submit a patch set from the command line.
87
Dariusz Luksza55750212015-03-04 16:28:30 +010088link:cmd-set-head.html[gerrit set-head]::
89 Change the HEAD reference of a project.
90
Hugo Arès345b93f2017-04-13 10:08:06 -040091link:cmd-set-project.html[gerrit set-project]::
92 Change a project's settings.
93
Gustaf Lundh7ed07a72018-08-20 15:02:15 +020094link:cmd-set-project-parent.html[gerrit set-project-parent]::
95 Change the project permissions are inherited from.
96
Hugo Arès169cb232015-01-08 15:40:06 -050097link:cmd-set-reviewers.html[gerrit set-reviewers]::
David Pursehouse4fd86432015-01-09 10:43:58 +090098 Add or remove reviewers on a change.
Hugo Arès169cb232015-01-08 15:40:06 -050099
Michael Kellyfc1c3dd2020-03-04 00:40:26 -0800100link:cmd-set-topic.html[gerrit set-topic]::
101 Set the topic for a change.
102
Shawn O. Pearce47769242011-06-14 16:40:48 -0700103link:cmd-stream-events.html[gerrit stream-events]::
Edwin Kempinf1acbb82011-09-15 12:49:42 +0200104 Monitor events occurring in real time.
Shawn O. Pearce47769242011-06-14 16:40:48 -0700105
Magnus Bäckf9b41a42012-09-25 12:20:39 -0400106link:cmd-version.html[gerrit version]::
107 Show the currently executing version of Gerrit.
108
Shawn O. Pearce93599bb2009-06-16 07:27:53 -0700109link:cmd-receive-pack.html[git receive-pack]::
Shawn O. Pearce4016a932009-05-28 15:12:40 -0700110 Standard Git server side command for client side `git push`.
111+
112Also implements the magic associated with uploading commits for
113review. See link:user-upload.html#push_create[Creating Changes].
114
Hugo Arès169cb232015-01-08 15:40:06 -0500115git upload-pack::
David Pursehouse4fd86432015-01-09 10:43:58 +0900116 Standard Git server side command for client side `git fetch`.
Mani Chandel7ec4ac72013-12-10 14:50:33 +0530117
Edwin Kempincf830d52018-08-29 08:36:08 +0200118[[admin_commands]]
119=== Administrator Commands
Shawn O. Pearce4016a932009-05-28 15:12:40 -0700120
Hugo Arès641fc782015-01-08 14:24:07 -0500121link:cmd-close-connection.html[gerrit close-connection]::
122 Close the specified SSH connection.
123
Matthias Sohn0572f5a2021-05-05 09:48:59 +0200124link:cmd-convert-ref-storage.html[gerrit convert-ref-storage]::
125 Convert ref storage to reftable (experimental).
126
Shawn O. Pearceb2ff7c82010-03-20 16:57:36 -0700127link:cmd-create-account.html[gerrit create-account]::
David Pursehousec2683992013-08-24 12:04:52 +0900128 Create a new user account.
Shawn O. Pearceb2ff7c82010-03-20 16:57:36 -0700129
Sasa Zivkov71963a52010-07-30 15:13:58 +0200130link:cmd-create-group.html[gerrit create-group]::
131 Create a new account group.
132
Shawn O. Pearce6e752212009-08-12 12:22:12 -0700133link:cmd-create-project.html[gerrit create-project]::
134 Create a new project and associated Git repository.
135
Shawn O. Pearce4016a932009-05-28 15:12:40 -0700136link:cmd-flush-caches.html[gerrit flush-caches]::
137 Flush some/all server caches from memory.
138
Edwin Kempin619169b2012-02-09 15:47:52 +0100139link:cmd-gc.html[gerrit gc]::
140 Run the Git garbage collection.
141
Khai Do71797a92016-02-25 14:06:21 -0800142link:cmd-index-activate.html[gerrit index activate]::
Hugo Arès47f15be2015-06-30 10:36:08 -0400143 Activate the latest index version available.
144
Hugo Arès3a593352015-06-29 16:04:59 -0400145link:cmd-index-start.html[gerrit index start]::
146 Start the online indexer.
147
David Pursehouse3f99e4e2016-05-20 15:37:18 +0900148link:cmd-index-changes.html[gerrit index changes]::
149 Index one or more changes.
150
Patrick Hiesel20d981e2018-07-04 09:48:21 +0200151link:cmd-index-changes-in-project.html[gerrit index changes-in-project]::
Hector Oswaldo Caballero2b4239a2017-02-13 07:40:33 -0500152 Index all the changes in one or more projects.
153
Simon Leic331a4e2014-08-08 11:12:38 -0400154link:cmd-logging-ls-level.html[gerrit logging ls-level]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900155 List loggers and their logging level.
Simon Leic331a4e2014-08-08 11:12:38 -0400156
157link:cmd-logging-set-level.html[gerrit logging set-level]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900158 Set the logging level of loggers.
Simon Leic331a4e2014-08-08 11:12:38 -0400159
Hugo Arès169cb232015-01-08 15:40:06 -0500160link:cmd-ls-user-refs.html[gerrit ls-user-refs]::
161 Lists refs visible for a specified user.
162
Marcin Czech992867e2021-11-04 16:32:41 +0100163link:cmd-migrate-externalids-to-insensitive.html[gerrit migrate-externalids-to-insensitive]::
164 Migrate external-ids to case insensitive.
165
Edwin Kempinf7295742012-07-16 15:03:46 +0200166link:cmd-plugin-install.html[gerrit plugin add]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900167 Alias for 'gerrit plugin install'.
Edwin Kempinf7295742012-07-16 15:03:46 +0200168
Brad Larsond5e87c32012-07-11 12:18:49 -0500169link:cmd-plugin-enable.html[gerrit plugin enable]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900170 Enable plugins.
Brad Larsond5e87c32012-07-11 12:18:49 -0500171
Edwin Kempinf7295742012-07-16 15:03:46 +0200172link:cmd-plugin-install.html[gerrit plugin install]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900173 Install/Add a plugin.
Edwin Kempinf7295742012-07-16 15:03:46 +0200174
175link:cmd-plugin-ls.html[gerrit plugin ls]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900176 List the installed plugins.
Edwin Kempinf7295742012-07-16 15:03:46 +0200177
178link:cmd-plugin-reload.html[gerrit plugin reload]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900179 Reload/Restart plugins.
Edwin Kempinf7295742012-07-16 15:03:46 +0200180
181link:cmd-plugin-remove.html[gerrit plugin remove]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900182 Disable plugins.
Edwin Kempinf7295742012-07-16 15:03:46 +0200183
184link:cmd-plugin-remove.html[gerrit plugin rm]::
David Pursehouse4fd86432015-01-09 10:43:58 +0900185 Alias for 'gerrit plugin remove'.
Edwin Kempinf7295742012-07-16 15:03:46 +0200186
Gustaf Lundhe0f52ff2018-04-16 10:51:47 +0200187link:cmd-reload-config.html[gerrit reload-config]::
188 Apply an updated gerrit.config.
189
Hugo Arès169cb232015-01-08 15:40:06 -0500190link:cmd-set-account.html[gerrit set-account]::
191 Change an account's settings.
192
David Ostrovsky958c8b72020-07-22 08:36:38 +0200193link:cmd-sequence-set.html[gerrit sequence set]::
194 Set new sequence value.
195
David Ostrovsky4f8df3392019-11-09 14:12:43 -0800196link:cmd-sequence-show.html[gerrit sequence show]::
David Pursehouse8095b862020-03-11 10:16:17 +0900197 Display current sequence value.
David Ostrovsky4f8df3392019-11-09 14:12:43 -0800198
Hugo Arès169cb232015-01-08 15:40:06 -0500199link:cmd-set-members.html[gerrit set-members]::
200 Set group members.
201
Hugo Arès169cb232015-01-08 15:40:06 -0500202link:cmd-show-caches.html[gerrit show-caches]::
203 Display current cache statistics.
204
205link:cmd-show-connections.html[gerrit show-connections]::
206 Display active client SSH connections.
207
208link:cmd-show-queue.html[gerrit show-queue]::
209 Display the background work queues, including replication.
210
Edwin Kempin55210d42013-03-26 10:30:26 +0100211link:cmd-test-submit-rule.html[gerrit test-submit rule]::
Johan Björk20ae0692012-08-02 15:57:13 +0200212 Test prolog submit rules.
213
Edwin Kempin48a9e0d2013-03-26 10:41:46 +0100214link:cmd-test-submit-type.html[gerrit test-submit type]::
215 Test prolog submit type.
216
Shawn O. Pearce3f1a13a2009-11-20 20:15:41 -0800217link:cmd-kill.html[kill]::
218 Kills a scheduled or running task.
219
220link:cmd-show-queue.html[ps]::
221 Alias for 'gerrit show-queue'.
222
Nasser Grainawi21f8fb42010-04-14 16:55:18 -0600223link:cmd-suexec.html[suexec]::
224 Execute a command as any registered user account.
225
Edwin Kempincf830d52018-08-29 08:36:08 +0200226[[trace]]
227=== Trace
Edwin Kempin0ade5aa2018-08-10 08:49:32 +0200228
229For executing SSH commands tracing can be enabled by setting the
Edwin Kempinda823782018-08-29 22:52:54 +0200230`--trace` and `--trace-id <trace-id>` options. It is recommended to use
231the ID of the issue that is being investigated as trace ID.
232
233----
234 $ ssh -p 29418 review.example.com gerrit create-project --trace --trace-id issue/123 foo/bar
235----
236
237It is also possible to omit the trace ID and get a unique trace ID
238generated.
Edwin Kempin0ade5aa2018-08-10 08:49:32 +0200239
240----
241 $ ssh -p 29418 review.example.com gerrit create-project --trace foo/bar
242----
243
244Enabling tracing results in additional logs with debug information that
245are written to the `error_log`. All logs that correspond to the traced
Edwin Kempinda823782018-08-29 22:52:54 +0200246request are associated with the trace ID. The trace ID is printed to
247the stderr command output:
Edwin Kempin0ade5aa2018-08-10 08:49:32 +0200248
249----
250 TRACE_ID: 1534174322774-7edf2a7b
251----
252
253Given the trace ID an administrator can find the corresponding logs and
254investigate issues more easily.
255
Edwin Kempinc67fa222021-08-04 09:30:27 +0200256[[deadline]]
257=== Setting a deadline
258
259When invoking an SSH command it's possible that the client sets a deadline
260after which the request should be aborted. To do this the
261`--deadline <deadline>` option must be set on the request. Values must be
262specified using standard time unit abbreviations ('ms', 'sec', 'min', etc.).
263
264----
265 $ ssh -p 29418 review.example.com gerrit create-project --deadline 5m foo/bar
266----
267
Shawn O. Pearce5500e692009-05-28 15:55:01 -0700268GERRIT
269------
270Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -0700271
272SEARCHBOX
273---------