1GIT-PUBLISH(1) git-publish Documentation GIT-PUBLISH(1)
2
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 No constraints are placed on git workflow, both vanilla git commands
17 and custom workflow scripts are compatible with git-publish.
18 Email sending and pull requests are fully integrated so that publishing
20 patches can be done in a single command.
21 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 -h
30 --help
31 Show help message and exit.
32 --annotate
34 Review and edit each patch email.
35 -b BASE
37 --base=BASE
38 Branch which this is based off (defaults to master).
39 --cc=CC
41 Specify a Cc: email recipient.
42 --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 --no-check-url
48 Do not check whether the pull request URL is publicly accessible.
49 --check-url
51 Check whether the pull request URL is publicly accessible. This is
52 the default.
53 --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 --no-inspect-emails
59 Do not prompt for confirmation before sending emails.
60 --inspect-emails
62 Show confirmation before sending emails.
63 -n NUMBER
65 --number=NUMBER
66 Explicitly specify the version number (auto-generated by default).
67 --no-message
69 --no-cover-letter
70 Do not add a message.
71 -m
73 --message
74 --cover-letter
75 Add a message.
76 --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 -p PROFILE_NAME
84 --profile=PROFILE_NAME
85 Select default settings from the given profile.
86 --pull-request
88 Tag and send as a pull request.
89 --sign-pull
91 Sign tag when sending pull request.
92 --no-sign-pull
94 Do not sign tag when sending pull request.
95 -k KEYID
97 --keyid=KEYID
98 Use the given GPG key to sign tag when sending pull request
99 --blurb-template
101 Use a pre-defined blurb message for the series HEAD.
102 --subject-prefix=PREFIX
104 Set the email Subject: header prefix.
105 --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 --setup
111 Add git alias in ~/.gitconfig so that the "git publish" git sub-
112 command works.
113 -t TOPIC
115 --topic=TOPIC
116 Set the topic name (defaults to current branch name).
117 --to=TO
119 Specify a primary email recipient.
120 -s
122 --signoff
123 Add Signed-off-by: <self> to commits when emailing.
124 --notes
126 Append the notes for the commit after the three-dash line. See
127 git-notes(1) for details.
128 --suppress-cc=SUPPRESS_CC
130 Override auto-cc when sending email. See git-send-email(1) for
131 details.
132 -v
134 --verbose
135 Show executed git commands (useful for troubleshooting).
136 --forget-cc
138 Forget all previous Cc: email addresses.
139 --override-to
141 Ignore any profile or saved To: email addresses.
142 --override-cc
144 Ignore any profile or saved Cc: email addresses.
145 -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 $ git-publish --setup
155 You can now use 'git publish' like a built-in git command.
157 Quickstart
159 Create a "topic branch" on which to do your work (implement a new
160 feature or fix a bug):
161 $ git checkout -b add-funny-jokes
163 ...
164 $ git commit
165 ...
166 $ git commit
167 Send a patch series via email:
169 $ git publish --to patches@example.org --cc maintainer@example.org
171 Address code review comments and send a new revision:
173 $ git rebase -i master
175 ...
176 $ git publish --to patches@example.org --cc maintainer@example.org
177 Refer back to older revisions:
179 $ git show add-funny-jokes-v1
181 This concludes the basic workflow for sending patch series.
183 Storing patch revisions
185 To store the first revision of a patch series:
186 $ git checkout my-feature
188 $ git publish
189 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 my-feature-v1
194 my-feature-v2
195 my-feature-v3
196 ...
197 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 Overriding the version number
203 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 $ git checkout my-existing-feature
209 $ git publish --number 7
210 This creates the my-existing-feature-v7 tag.
212 Overriding the branch name
214 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 $ git checkout branch-a
223 $ git publish --topic branch-b
224 This creates branch-b-v1 instead of branch-a-v1 and can be used to skip
226 the check for 'master'.
227 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 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 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 To insist on creating a tag message:
244 $ git publish --message
246 To refrain from creating a tag message:
248 $ git publish --no-message
250 For convenience these options are also available as --cover-letter and
252 --no-cover-letter just like in git-format-patch(1).
253 Editing tag messages without publishing
255 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 To edit the tag message without publishing:
261 $ git publish --edit
263 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 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 $ git publish --base my-parent
277 Most of the time 'master' works fine.
279 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 $ git config git-publish.base origin/master # for all branches
286 $ git config branch.foo.gitpublishbase origin/master # for one branch
287 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 $ git publish --to patches@example.org \
294 --cc alex@example.org --cc bob@example.org
295 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 The git-send-email(1) aliasesfile feature works since the email
301 addresses are passed through without interpretation by git-publish.
302 Patch emails can be manually edited before being sent, these changes
304 only affect outgoing emails and are not stored permanently:
305 $ git publish --to patches@example.org --annotate
307 git-publish can background itself so patch emails can be inspected from
309 the shell:
310 $ git publish --to patches@example.org --inspect-emails
312 Signed-off-by: <self> lines can be applied to patch emails, only
314 outgoing emails are affected and not the local git commits:
315 $ git publish --to patches@example.org --signoff
317 Sending [RFC] series instead of regular [PATCH] series can be done by
319 customizing the Subject: line:
320 $ git publish --to patches@example.org --subject-prefix RFC
322 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 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 $ git publish --clear-subject-prefix
332 git-publish remembers the list of addresses CC'd on previous revisions
334 of a patchset by default. To clear that internal list:
335 $ git publish --to patches@example.org --forget-cc --cc new@example.org
337 In the above example, new@example.org will be saved to the internal
339 list for next time.
340 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 $ git-publish --cc old@example.org
346 To temporarily ignore any CCs in the profile or saved list, and send
348 only to the addresses specified on the CLI:
349 $ git-publish --override-cc --cc onetime@example.org --to patches@example.org
351 CCs specified alongside --override-cc are not remembered for future
353 revisions.
354 $ git publish --to patches@example.org --notes
356 To include git-notes into a patch.
358 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 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 $ 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 The "example" profile is equivalent to the following command-line:
381 $ git publish --subject-prefix 'PATCH for-example' --to patches@example.org --cc maintainer1@example.org --cc maintainer2@example.org
383 If command-line options are given together with a profile, then the
385 command-line options take precedence.
386 The following profile options are available:
388 [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 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 $ cat >>.git/config
407 [gitpublishprofile "default"]
408 suppresscc = all # do not auto-cc people
409 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 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 Ensure that the branch has a default remote repository saved:
423 $ git config branch.foo.remote my-public-repo
425 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 [remote "<name>"]
433 url = https://myhost.com/repo.git
434 pushurl = me@myhost.com:repo.git
435 Send a pull request:
437 $ 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 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 The following configuration options are available:
450 branch.BRANCHNAME.gitpublishbase
452 gitpublishprofile.PROFILENAME.base
453 git-publish.base
454 Same as the --base option.
455 branch.BRANCHNAME.gitpublishto
457 gitpublishprofile.PROFILENAME.to
458 Same as the --to option.
459 branch.BRANCHNAME.gitpublishcc
461 gitpublishprofile.PROFILENAME.cc
462 Same as the --cc option.
463 branch.BRANCHNAME.gitpublishcccmd
465 gitpublishprofile.PROFILENAME.gitpublishcccmd
466 Same as the --cc-cmd option.
467 gitpublishprofile.PROFILENAME.remote
469 The remote where the pull request tag will be pushed.
470 gitpublishprofile.PROFILENAME.message
472 Same as the --message option.
473 branch.BRANCHNAME.gitpublishprefix
475 gitpublishprofile.PROFILENAME.prefix
476 Same as the --subject-prefix option.
477 gitpublishprofile.PROFILENAME.suppresscc
479 Same as the --suppress-cc option.
480 gitpublishprofile.PROFILENAME.signoff
482 Same as the --signoff option.
483 gitpublishprofile.PROFILENAME.inspect-emails
485 Same as the --inspect-emails option.
486 gitpublishprofile.PROFILENAME.notes
488 Same as the --notes option.
489 gitpublishprofile.PROFILENAME.checkUrl
491 git-publish.checkUrl
492 Same as the --no-check-url and --check-url options.
493 gitpublishprofile.PROFILENAME.signPull
495 git-publish.signPull
496 Same as the --no-sign-pull and --sign-pull options.
497 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 Available hooks include:
508 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 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
5281.8.1 2022-05-05 GIT-PUBLISH(1)