1GIT-PUBLISH(1)             git-publish Documentation            GIT-PUBLISH(1)
2
3
4

NAME

6       git-publish - Prepare and store patch revisions as git tags
7

SYNOPSIS

9         git-publish [options] -- [common format-patch options]
10

DESCRIPTION

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

OPTIONS

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

DISCUSSION

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

CONFIGURATION

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

HOOKS

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

SEE ALSO

520       git-format-patch(1), git-send-email(1), git-config(1), git-notes(1),
521       githooks(5)
522

AUTHOR

524       Stefan Hajnoczi <mailto:stefanha@gmail.com>
525
527       Copyright (C) 2011-2018 Stefan Hajnoczi
528
529
530
5311.8.1                             2023-07-19                    GIT-PUBLISH(1)
Impressum