1GIT-PUBLISH(1) git-publish Documentation GIT-PUBLISH(1)
2
3
4
6 git-publish - Prepare and store patch revisions as git tags
7
9 git-publish [options] -- [common format-patch options]
10
12 git-publish prepares patches and stores them as git tags for future
13 reference. It works with individual patches as well as patch series.
14 Revision numbering is handled automatically.
15
16 No constraints are placed on git workflow, both vanilla git commands
17 and custom workflow scripts are compatible with git-publish.
18
19 Email sending and pull requests are fully integrated so that publishing
20 patches can be done in a single command.
21
22 Hook scripts are invoked during patch preparation so that custom checks
23 or test runs can be automated.
24
26 --version
27 Show program's version number and exit.
28
29 -h
30 --help
31 Show help message and exit.
32
33 --annotate
34 Review and edit each patch email.
35
36 -b BASE
37 --base=BASE
38 Branch which this is based off (defaults to master).
39
40 --cc=CC
41 Specify a Cc: email recipient.
42
43 --cc-cmd=CC_CMD
44 Specify a command add whose output to add the Cc: email recipient
45 list. See git-send-email(1) for details.
46
47 --no-check-url
48 Do not check whether the pull request URL is publicly accessible.
49
50 --check-url
51 Check whether the pull request URL is publicly accessible. This is
52 the default.
53
54 --edit
55 Edit message but do not tag a new version. Use this to draft the
56 cover letter before actually tagging a new version.
57
58 --no-inspect-emails
59 Do not prompt for confirmation before sending emails.
60
61 --inspect-emails
62 Show confirmation before sending emails.
63
64 -n NUMBER
65 --number=NUMBER
66 Explicitly specify the version number (auto-generated by default).
67
68 --no-message
69 --no-cover-letter
70 Do not add a message.
71
72 -m
73 --message
74 --cover-letter
75 Add a message.
76
77 --no-binary
78 Do not output contents of changes in binary files, instead display
79 a notice that those files changed. Patches generated using this
80 option cannot be applied properly, but they are still useful for
81 code review.
82
83 -p PROFILE_NAME
84 --profile=PROFILE_NAME
85 Select default settings from the given profile.
86
87 --pull-request
88 Tag and send as a pull request.
89
90 --sign-pull
91 Sign tag when sending pull request.
92
93 --no-sign-pull
94 Do not sign tag when sending pull request.
95
96 -k KEYID
97 --keyid=KEYID
98 Use the given GPG key to sign tag when sending pull request
99
100 --blurb-template
101 Use a pre-defined blurb message for the series HEAD.
102
103 --subject-prefix=PREFIX
104 Set the email Subject: header prefix.
105
106 --clear-subject-prefix
107 Clear the per-branch subject prefix. The subject prefix persists
108 between versions by default. Use this option to reset it.
109
110 --setup
111 Add git alias in ~/.gitconfig so that the "git publish" git sub-
112 command works.
113
114 -t TOPIC
115 --topic=TOPIC
116 Set the topic name (defaults to current branch name).
117
118 --to=TO
119 Specify a primary email recipient.
120
121 -s
122 --signoff
123 Add Signed-off-by: <self> to commits when emailing.
124
125 --notes
126 Append the notes for the commit after the three-dash line. See
127 git-notes(1) for details.
128
129 --suppress-cc=SUPPRESS_CC
130 Override auto-cc when sending email. See git-send-email(1) for
131 details.
132
133 -v
134 --verbose
135 Show executed git commands (useful for troubleshooting).
136
137 --forget-cc
138 Forget all previous Cc: email addresses.
139
140 --override-to
141 Ignore any profile or saved To: email addresses.
142
143 --override-cc
144 Ignore any profile or saved Cc: email addresses.
145
146 -R IN_REPLY_TO
147 --in-reply-to=IN_REPLY_TO
148 Specify the In-Reply-To: of the cover letter (or the single patch).
149
151 Setup
152 Run git-publish in setup mode to configure the git alias:
153
154 $ git-publish --setup
155
156 You can now use 'git publish' like a built-in git command.
157
158 Quickstart
159 Create a "topic branch" on which to do your work (implement a new
160 feature or fix a bug):
161
162 $ git checkout -b add-funny-jokes
163 ...
164 $ git commit
165 ...
166 $ git commit
167
168 Send a patch series via email:
169
170 $ git publish --to patches@example.org --cc maintainer@example.org
171
172 Address code review comments and send a new revision:
173
174 $ git rebase -i master
175 ...
176 $ git publish --to patches@example.org --cc maintainer@example.org
177
178 Refer back to older revisions:
179
180 $ git show add-funny-jokes-v1
181
182 This concludes the basic workflow for sending patch series.
183
184 Storing patch revisions
185 To store the first revision of a patch series:
186
187 $ git checkout my-feature
188 $ git publish
189
190 This creates the my-feature-v1 git tag. Running git-publish again at a
191 later point will create tags with incrementing version numbers:
192
193 my-feature-v1
194 my-feature-v2
195 my-feature-v3
196 ...
197
198 To refer back to a previous version, simply check out that git tag.
199 This way a record is kept of each patch revision that has been
200 published.
201
202 Overriding the version number
203
204 The version number can be set manually. This is handy when starting
205 out with git-publish on branches that were previously manually
206 versioned:
207
208 $ git checkout my-existing-feature
209 $ git publish --number 7
210
211 This creates the my-existing-feature-v7 tag.
212
213 Overriding the branch name
214
215 By default git-publish refuses to create a revision for the 'master'
216 branch. Usually one works with so-called topic branches, one branch
217 for each feature under development. Using the 'master' branch may
218 indicate that one has forgotten to switch onto the intended topic
219 branch. It is possible to override the topic name and even publish on
220 'master':
221
222 $ git checkout branch-a
223 $ git publish --topic branch-b
224
225 This creates branch-b-v1 instead of branch-a-v1 and can be used to skip
226 the check for 'master'.
227
228 Tag messages
229 Tag messages have a summary (or subject line) and a description (or
230 blurb). When send email integration is used the summary is put into
231 the cover letter Subject: line while the description is put into the
232 body.
233
234 When prompting for tag messages on v2, v3, or other incremental
235 revisions, the previous revision's tag message is used as the starting
236 point. This is handy for updating the existing description and keeping
237 a changelog of the difference between revisions.
238
239 The git-config(1) format.coverLetter value is honored. The default
240 'auto' value adds a cover letter if there is more than 1 patch. The
241 cover letter can also be forced with 'true' or 'false'.
242
243 To insist on creating a tag message:
244
245 $ git publish --message
246
247 To refrain from creating a tag message:
248
249 $ git publish --no-message
250
251 For convenience these options are also available as --cover-letter and
252 --no-cover-letter just like in git-format-patch(1).
253
254 Editing tag messages without publishing
255
256 Sometimes it is useful to edit the tag message before publishing. This
257 can be used to note down changelog entries as you prepare the next
258 version of a patch series.
259
260 To edit the tag message without publishing:
261
262 $ git publish --edit
263
264 This does not tag a new version. Instead a -staging tag will be
265 created and the tag message will be picked up when you publish next
266 time. For example, if you on branch my-feature and have already
267 published v1 and v2, editing the tag message will create the tag my-
268 feature-staging. When you publish next time the my-feature-v3 tag will
269 be created and use the tag message you staged earlier.
270
271 Setting the base branch
272 git-publish detects whether the branch contains a single commit or
273 multiple commits by comparing against a base branch ('master' by
274 default). You can specify the base branch like this:
275
276 $ git publish --base my-parent
277
278 Most of the time 'master' works fine.
279
280 It is also possible to persist which base branch to use. This is
281 useful if you find yourself often specifying a base branch manually.
282 It can be done globally for all branches in a reposity or just for a
283 specific branch:
284
285 $ git config git-publish.base origin/master # for all branches
286 $ git config branch.foo.gitpublishbase origin/master # for one branch
287
288 Send email integration
289 git-publish can call git-send-email(1) after creating a git tag. If
290 there is a tag message it will be used as the cover letter. Email can
291 be sent like this:
292
293 $ git publish --to patches@example.org \
294 --cc alex@example.org --cc bob@example.org
295
296 After the git tag has been created as usual, commits on top of the base
297 branch are sent as the patch series. The base branch defaults to
298 'master' and can be set manually with --base.
299
300 The git-send-email(1) aliasesfile feature works since the email
301 addresses are passed through without interpretation by git-publish.
302
303 Patch emails can be manually edited before being sent, these changes
304 only affect outgoing emails and are not stored permanently:
305
306 $ git publish --to patches@example.org --annotate
307
308 git-publish can background itself so patch emails can be inspected from
309 the shell:
310
311 $ git publish --to patches@example.org --inspect-emails
312
313 Signed-off-by: <self> lines can be applied to patch emails, only
314 outgoing emails are affected and not the local git commits:
315
316 $ git publish --to patches@example.org --signoff
317
318 Sending [RFC] series instead of regular [PATCH] series can be done by
319 customizing the Subject: line:
320
321 $ git publish --to patches@example.org --subject-prefix RFC
322
323 Using this way, specified "--subject-prefix" will be stored as per-
324 branch subject prefix, and will be used for the next git-publish as
325 well.
326
327 One can override the stored per-branch subject prefix by providing the
328 --subject-prefix parameter again, or to clear it permanently, we can
329 use:
330
331 $ git publish --clear-subject-prefix
332
333 git-publish remembers the list of addresses CC'd on previous revisions
334 of a patchset by default. To clear that internal list:
335
336 $ git publish --to patches@example.org --forget-cc --cc new@example.org
337
338 In the above example, new@example.org will be saved to the internal
339 list for next time.
340
341 CC addresses accumulate and cascade. Following the previous example, if
342 we want to send a new version to both new@example.org and
343 old@example.org:
344
345 $ git-publish --cc old@example.org
346
347 To temporarily ignore any CCs in the profile or saved list, and send
348 only to the addresses specified on the CLI:
349
350 $ git-publish --override-cc --cc onetime@example.org --to patches@example.org
351
352 CCs specified alongside --override-cc are not remembered for future
353 revisions.
354
355 $ git publish --to patches@example.org --notes
356
357 To include git-notes into a patch.
358
359 One can attach notes to a commit with `git notes add <object>`. For
360 having the notes "following" a commit on rebase operation, you can use
361 `git config notes.rewriteRef refs/notes/commits`. For more information,
362 give a look at git-notes(1).
363
364 Creating profiles for frequently used projects
365 Instead of providing command-line options each time a patch series is
366 published, the options can be stored in git-config(1) files:
367
368 $ cat >>.git/config
369 [gitpublishprofile "example"]
370 prefix = PATCH for-example
371 to = patches@example.org
372 cc = maintainer1@example.org
373 cc = maintainer2@example.org
374 ^D
375 $ git checkout first-feature
376 $ git publish --profile example
377 $ git checkout second-feature
378 $ git publish --profile example
379
380 The "example" profile is equivalent to the following command-line:
381
382 $ git publish --subject-prefix 'PATCH for-example' --to patches@example.org --cc maintainer1@example.org --cc maintainer2@example.org
383
384 If command-line options are given together with a profile, then the
385 command-line options take precedence.
386
387 The following profile options are available:
388
389 [gitpublishprofile "example"]
390 base = v2.1.0 # same as --base
391 remote = origin # used if branch.<branch-name>.remote not set
392 prefix = PATCH # same as --patch
393 to = patches@example.org # same as --to
394 cc = maintainer@example.org # same as --cc
395 suppresscc = all # same as --suppress-cc
396 message = true # same as --message
397 signoff = true # same as --signoff
398 inspect-emails = true # same as --inspect-emails
399 notes = true # same as --notes
400 blurb-template = A blurb template # same as --blurb-template
401
402 The special "default" profile name is active when no --profile command-
403 line option was given. The default profile does not set any options
404 but can be extended in git-config(1) files:
405
406 $ cat >>.git/config
407 [gitpublishprofile "default"]
408 suppresscc = all # do not auto-cc people
409
410 If a file named .gitpublish exists in the repository top-level
411 directory, it is automatically searched in addition to the
412 git-config(1) .git/config and ~/.gitconfig files. Since the
413 .gitpublish file can be committed into git, this can be used to provide
414 a default profile for branches that you expect to repeatedly use as a
415 base for new work.
416
417 Sending pull requests
418 git-publish can send signed pull requests. Signed tags are pushed to a
419 remote git repository that must be readable by the person who will
420 merge the pull request.
421
422 Ensure that the branch has a default remote repository saved:
423
424 $ git config branch.foo.remote my-public-repo
425
426 The remote must be accessible to the person receiving the pull request.
427 Normally the remote URI should be git:// or https://. If the remote is
428 configured for ssh:// then git-config(1) can be supplemented with a
429 public url and private pushurl. This ensures that pull requests always
430 use the public URI:
431
432 [remote "<name>"]
433 url = https://myhost.com/repo.git
434 pushurl = me@myhost.com:repo.git
435
436 Send a pull request:
437
438 $ git publish --pull-request --to patches@example.org --annotate
439
441 There are three possible levels of configuration with the following
442 order of precedence:
443
444 1. Per-branch options only apply to a specific branch.
445 2. Per-profile options apply when the profile is enabled with
446 --profile.
447 3. Global options apply in all cases.
448
449 The following configuration options are available:
450
451 branch.BRANCHNAME.gitpublishbase
452 gitpublishprofile.PROFILENAME.base
453 git-publish.base
454 Same as the --base option.
455
456 branch.BRANCHNAME.gitpublishto
457 gitpublishprofile.PROFILENAME.to
458 Same as the --to option.
459
460 branch.BRANCHNAME.gitpublishcc
461 gitpublishprofile.PROFILENAME.cc
462 Same as the --cc option.
463
464 branch.BRANCHNAME.gitpublishcccmd
465 gitpublishprofile.PROFILENAME.gitpublishcccmd
466 Same as the --cc-cmd option.
467
468 gitpublishprofile.PROFILENAME.remote
469 The remote where the pull request tag will be pushed.
470
471 gitpublishprofile.PROFILENAME.message
472 Same as the --message option.
473
474 branch.BRANCHNAME.gitpublishprefix
475 gitpublishprofile.PROFILENAME.prefix
476 Same as the --subject-prefix option.
477
478 gitpublishprofile.PROFILENAME.suppresscc
479 Same as the --suppress-cc option.
480
481 gitpublishprofile.PROFILENAME.signoff
482 Same as the --signoff option.
483
484 gitpublishprofile.PROFILENAME.inspect-emails
485 Same as the --inspect-emails option.
486
487 gitpublishprofile.PROFILENAME.notes
488 Same as the --notes option.
489
490 gitpublishprofile.PROFILENAME.checkUrl
491 git-publish.checkUrl
492 Same as the --no-check-url and --check-url options.
493
494 gitpublishprofile.PROFILENAME.signPull
495 git-publish.signPull
496 Same as the --no-sign-pull and --sign-pull options.
497
498 git-publish.signingkey
499 Same as the --keyid option.
500
502 git-publish supports the githooks(5) mechanism for running user scripts
503 at important points during the workflow. The script can influence the
504 outcome of the operation, for example, by rejecting a patch series that
505 is about to be sent out.
506
507 Available hooks include:
508
509 pre-publish-send-email
510 Invoked before git-send-email(1). Takes the path to the patches
511 directory as an argument. If the exit code is non-zero, the series
512 will not be sent.
513
514 pre-publish-tag
515 Invoked before creating the -staging tag on current branch. Takes
516 one argument which refers to the base commit or branch. If the
517 exit code is non-zero, git-publish will abort.
518
520 git-format-patch(1), git-send-email(1), git-config(1), git-notes(1),
521 githooks(5)
522
524 Stefan Hajnoczi <mailto:stefanha@gmail.com>
525
527 Copyright (C) 2011-2018 Stefan Hajnoczi
528
529
530
5311.5.0 2019-07-25 GIT-PUBLISH(1)