Setup
Run git-publish in setup mode to configure the git alias:
$ git-publish --setup
You can now use 'git publish' like a built-in git command.
Quickstart
Create a "topic branch" on which to do your work (implement a new feature or fix a bug):
$ git checkout -b add-funny-jokes
...
$ git commit
...
$ git commit
Send a patch series via email:
$ git publish --to patches@example.org --cc maintainer@example.org
Address code review comments and send a new revision:
$ git rebase -i master
...
$ git publish --to patches@example.org --cc maintainer@example.org
Refer back to older revisions:
$ git show add-funny-jokes-v1
This concludes the basic workflow for sending patch series.
Storingpatchrevisions
To store the first revision of a patch series:
$ git checkout my-feature
$ git publish
This creates the my-feature-v1 git tag. Running git-publish again at a later point will create tags with
incrementing version numbers:
my-feature-v1
my-feature-v2
my-feature-v3
...
To refer back to a previous version, simply check out that git tag. This way a record is kept of each
patch revision that has been published.
Overridingtheversionnumber
The version number can be set manually. This is handy when starting out with git-publish on branches
that were previously manually versioned:
$ git checkout my-existing-feature
$ git publish --number 7
This creates the my-existing-feature-v7 tag.
Overridingthebranchname
By default git-publish refuses to create a revision for the 'master' branch. Usually one works with so-
called topic branches, one branch for each feature under development. Using the 'master' branch may
indicate that one has forgotten to switch onto the intended topic branch. It is possible to override the
topic name and even publish on 'master':
$ git checkout branch-a
$ git publish --topic branch-b
This creates branch-b-v1 instead of branch-a-v1 and can be used to skip the check for 'master'.
Tagmessages
Tag messages have a summary (or subject line) and a description (or blurb). When send email integration
is used the summary is put into the cover letter Subject: line while the description is put into the
body.
When prompting for tag messages on v2, v3, or other incremental revisions, the previous revision's tag
message is used as the starting point. This is handy for updating the existing description and keeping a
changelog of the difference between revisions.
The git-config(1) format.coverLetter value is honored. The default 'auto' value adds a cover letter if
there is more than 1 patch. The cover letter can also be forced with 'true' or 'false'.
To insist on creating a tag message:
$ git publish --message
To refrain from creating a tag message:
$ git publish --no-message
For convenience these options are also available as --cover-letter and --no-cover-letter just like in
git-format-patch(1).
Editingtagmessageswithoutpublishing
Sometimes it is useful to edit the tag message before publishing. This can be used to note down
changelog entries as you prepare the next version of a patch series.
To edit the tag message without publishing:
$ git publish --edit
This does not tag a new version. Instead a -staging tag will be created and the tag message will be
picked up when you publish next time. For example, if you on branch my-feature and have already
published v1 and v2, editing the tag message will create the tag my-feature-staging. When you publish
next time the my-feature-v3 tag will be created and use the tag message you staged earlier.
Settingthebasebranch
git-publish detects whether the branch contains a single commit or multiple commits by comparing against
a base branch ('master' by default). You can specify the base branch like this:
$ git publish --base my-parent
Most of the time 'master' works fine.
It is also possible to persist which base branch to use. This is useful if you find yourself often
specifying a base branch manually. It can be done globally for all branches in a reposity or just for a
specific branch:
$ git config git-publish.base origin/master # for all branches
$ git config branch.foo.gitpublishbase origin/master # for one branch
Sendemailintegration
git-publish can call git-send-email(1) after creating a git tag. If there is a tag message it will be
used as the cover letter. Email can be sent like this:
$ git publish --to patches@example.org \
--cc alex@example.org --cc bob@example.org
After the git tag has been created as usual, commits on top of the base branch are sent as the patch
series. The base branch defaults to 'master' and can be set manually with --base.
The git-send-email(1) aliasesfile feature works since the email addresses are passed through without
interpretation by git-publish.
Patch emails can be manually edited before being sent, these changes only affect outgoing emails and are
not stored permanently:
$ git publish --to patches@example.org --annotate
git-publish can background itself so patch emails can be inspected from the shell:
$ git publish --to patches@example.org --inspect-emails
Signed-off-by: <self> lines can be applied to patch emails, only outgoing emails are affected and not the
local git commits:
$ git publish --to patches@example.org --signoff
Sending [RFC] series instead of regular [PATCH] series can be done by customizing the Subject: line:
$ git publish --to patches@example.org --subject-prefix RFC
Using this way, specified "--subject-prefix" will be stored as per-branch subject prefix, and will be
used for the next git-publish as well.
One can override the stored per-branch subject prefix by providing the --subject-prefix parameter again,
or to clear it permanently, we can use:
$ git publish --clear-subject-prefix
git-publish remembers the list of addresses CC'd on previous revisions of a patchset by default. To clear
that internal list:
$ git publish --to patches@example.org --forget-cc --cc new@example.org
In the above example, new@example.org will be saved to the internal list for next time.
CC addresses accumulate and cascade. Following the previous example, if we want to send a new version to
both new@example.org and old@example.org:
$ git-publish --cc old@example.org
To temporarily ignore any CCs in the profile or saved list, and send only to the addresses specified on
the CLI:
$ git-publish --override-cc --cc onetime@example.org --to patches@example.org
CCs specified alongside --override-cc are not remembered for future revisions.
$ git publish --to patches@example.org --notes
To include git-notes into a patch.
One can attach notes to a commit with `git notes add <object>`. For having the notes "following" a commit
on rebase operation, you can use `git config notes.rewriteRef refs/notes/commits`. For more information,
give a look at git-notes(1).
Creatingprofilesforfrequentlyusedprojects
Instead of providing command-line options each time a patch series is published, the options can be
stored in git-config(1) files:
$ cat >>.git/config
[gitpublishprofile "example"]
prefix = PATCH for-example
to = patches@example.org
cc = maintainer1@example.org
cc = maintainer2@example.org
^D
$ git checkout first-feature
$ git publish --profile example
$ git checkout second-feature
$ git publish --profile example
The "example" profile is equivalent to the following command-line:
$ git publish --subject-prefix 'PATCH for-example' --to patches@example.org --cc maintainer1@example.org --cc maintainer2@example.org
If command-line options are given together with a profile, then the command-line options take precedence.
The following profile options are available:
[gitpublishprofile "example"]
base = v2.1.0 # same as --base
remote = origin # used if branch.<branch-name>.remote not set
prefix = PATCH # same as --patch
to = patches@example.org # same as --to
cc = maintainer@example.org # same as --cc
suppresscc = all # same as --suppress-cc
message = true # same as --message
signoff = true # same as --signoff
inspect-emails = true # same as --inspect-emails
notes = true # same as --notes
blurb-template = A blurb template # same as --blurb-template
The special "default" profile name is active when no --profile command-line option was given. The
default profile does not set any options but can be extended in git-config(1) files:
$ cat >>.git/config
[gitpublishprofile "default"]
suppresscc = all # do not auto-cc people
If a file named .gitpublish exists in the repository top-level directory, it is automatically searched in
addition to the git-config(1) .git/config and ~/.gitconfig files. Since the .gitpublish file can be
committed into git, this can be used to provide a default profile for branches that you expect to
repeatedly use as a base for new work.
Sendingpullrequests
git-publish can send signed pull requests. Signed tags are pushed to a remote git repository that must
be readable by the person who will merge the pull request.
Ensure that the branch has a default remote repository saved:
$ git config branch.foo.remote my-public-repo
The remote must be accessible to the person receiving the pull request. Normally the remote URI should
be git:// or https://. If the remote is configured for ssh:// then git-config(1) can be supplemented
with a public url and private pushurl. This ensures that pull requests always use the public URI:
[remote "<name>"]
url = https://myhost.com/repo.git
pushurl = me@myhost.com:repo.git
Send a pull request:
$ git publish --pull-request --to patches@example.org --annotate
Install Now
PNG Icons
