GIT-PUBLISH(1)

📦
version 1.8.2 · 6 versions
, in fedora 43

💅 GIT-PUBLISH(1) — git-publish Documentation

okay bestie, welcome to the git-publish manual page, straight outta the git-publish Documentation set. this is the one you've been waiting for. grab a strawberry 🍓 and let's go.

✨ NAME ✨

git-publish — prepare and store patch revisions as git tags

🦋 SYNOPSIS 🦋

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

💖 DESCRIPTION 💖

so like, git-publish prepares patches and stores them as git tags so you have them for future reference. it works with individual patches and whole patch series, and the revision numbering? handled automatically. you don't have to think about it. it's giving effortless. ✨

no constraints are placed on your git workflow, okay? none. both vanilla git commands and custom workflow scripts are compatible with git-publish. do your thing, queen. 👑

email sending and pull requests are fully integrated, so publishing patches can be done in a single command. one command. that's it. that's the whole vibe. 💅

hook scripts get invoked during patch preparation, so custom checks or test runs can be automated. it's giving set it and forget it. 🎀

🔥 OPTIONS 🔥

  • --version — Show program's version number and exit. short and sweet, love that for us.
  • -h, --help — Show help message and exit. the classic. the icon. the legend. 👑
  • --annotate — Review and edit each patch email. yes, each one. main character energy for every single email.
  • -b BASE, --base=BASE — Branch which this is based off (defaults to master). so like, where are we branching from, bestie? defaults to master if you don't say.
  • --cc=CC — Specify a Cc: email recipient. tag them in, bestie. 🫶
  • --cc-cmd=CC_CMD — Specify a command add whose output to add the Cc: email recipient list. See git-send-email(1) for details. yeah we're letting a whole command pick your cc list, iykyk.
  • --no-check-url — Do not check whether the pull request URL is publicly accessible.
  • --check-url — Check whether the pull request URL is publicly accessible. This is the default. lowkey responsible of it tbh.
  • --skip=N — Unselect the first N patch emails (including the cover letter if any). If negative, select only the last -N patches. so you can skip from the front, or grab from the back if it's negative. ✨
  • --edit — Edit message but do not tag a new version. Use this to draft the cover letter before actually tagging a new version. drafting era. 📝
  • --no-inspect-emails — Do not prompt for confirmation before sending emails. living dangerously, no notes. 💀
  • --inspect-emails — Show confirmation before sending emails. the responsible girlie option.
  • -n NUMBER, --number=NUMBER — Explicitly specify the version number (auto-generated by default). you can pick your own number but like, it already does this for you.
  • --no-message, --no-cover-letter — Do not add a message.
  • -m, --message, --cover-letter — Add a message. ✨
  • --no-binary — Do not output contents of changes in binary files, instead display a notice that those files changed. Patches generated using this option cannot be applied properly, but they are still useful for code review.
⚠️ okay heads up: with --no-binary your patches cannot be applied properly. they're still useful for code review tho, so like, it's a tradeoff. know what you're getting into. 🫣
  • -p PROFILE_NAME, --profile=PROFILE_NAME — Select default settings from the given profile. presets, but make it fashion. 🎀
  • --pull-request — Tag and send as a pull request.
  • --sign-pull — Sign tag when sending pull request.
  • --no-sign-pull — Do not sign tag when sending pull request.
  • -k KEYID, --keyid=KEYID — Use the given GPG key to sign tag when sending pull request
  • --blurb-template — Use a pre-defined blurb message for the series HEAD.
  • --subject-prefix=PREFIX — Set the email Subject: header prefix.
  • --clear-subject-prefix — Clear the per-branch subject prefix. The subject prefix persists between versions by default. Use this option to reset it. it's been holding onto that prefix forever, bestie. time to let it go. 🦋
  • --setup — Add git alias in ~/.gitconfig so that the git publish git sub-command works. one-time glow-up for your config. ✨
  • -t TOPIC, --topic=TOPIC — Set the topic name (defaults to current branch name).
  • --to=TO — Specify a primary email recipient.
  • -s, --signoff — Add Signed-off-by: <self> to commits when emailing.
  • --notes — Append the notes for the commit after the three-dash line. See git-notes(1) for details.
  • --suppress-cc=SUPPRESS_CC — Override auto-cc when sending email. See git-send-email(1) for details.
  • -v, --verbose — Show executed git commands (useful for troubleshooting). when something's acting up and you need to see everything. 🔍
  • --forget-cc — Forget all previous Cc: email addresses. memory wipe. it never happened. 💀
  • --override-to — Ignore any profile or saved To: email addresses.
  • --override-cc — Ignore any profile or saved Cc: email addresses.
  • -R IN_REPLY_TO, --in-reply-to=IN_REPLY_TO — Specify the In-Reply-To: of the first email, or of all emails if --no-thread is given or is otherwise the default.
  • --no-thread — Do not add In-Reply-To: and References: headers to any email. This may be the default depending on your git-send-email(1) configuration.
  • --thread — Add In-Reply-To: and References: headers to sent emails. This may be the default depending on your git-send-email(1) configuration, which also controls whether each email refers to the previous email or to the first email.
  • --send-email-args — List of arguments that are forwarded to the git-send-email call. You can add as many arguments as you need by using consecutive --send-email-args arguments. stack 'em up, bestie. 🧚

💬 DISCUSSION 💬

Okay bestie, so now we're getting into the actual how-to. This is where it gets good. ✨

🛠️ Setup 🛠️

First things first: run git-publish in setup mode to configure the git alias. Like this:

$ git-publish --setup

Boom. Now you can use git publish just like it's a built-in git command. No cap. 💅

🚀 Quickstart 🚀

So you wanna do some work? Make a "topic branch" for your feature or bug fix. Like:

$ git checkout -b add-funny-jokes
...
$ git commit
...
$ git commit

Then send a patch series via email:

$ git publish --to patches@example.org --cc maintainer@example.org

Get some review comments? Address them and send a new revision:

$ git rebase -i master
...
$ git publish --to patches@example.org --cc maintainer@example.org

Wanna look back at older revisions? Easy:

$ git show add-funny-jokes-v1

And that's the basic workflow for sending patch series. Iconic. 👑

📦 Storing patch revisions 📦

To store the first revision of a patch series:

$ git checkout my-feature
$ git publish

This creates the my-feature-v1 git tag. Run git-publish again later and it'll make tags with incrementing version numbers:

my-feature-v1
my-feature-v2
my-feature-v3
...

To refer back to a previous version, just check out that git tag. That way you keep a record of each patch revision you've published. Obsessed. 💖

🔢 Overriding the version number 🔢

You can set the version number manually. Super handy if you're starting 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. Slay.

🌿 Overriding the branch name 🌿

By default, git-publish refuses to create a revision for the 'master' branch. Usually you work with topic branches—one branch per feature. Using 'master' might mean you forgot to switch to your topic branch. But you can 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'. Yasss.

🏷️ Tag messages 🏷️

Tag messages have a summary (or subject line) and a description (or blurb). When you use send email integration, the summary goes into the cover letter Subject: line and the description goes 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). Periodt. 💅

✏️ Editing tag messages without publishing ✏️

Sometimes it's useful to edit the tag message before publishing. You can 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're 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. Big brain energy. 🧠

🧱 Setting the base branch 🧱

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's also possible to persist which base branch to use. This is useful if you find yourself often specifying a base branch manually. You can do it globally for all branches in a repository 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

Lowkey a lifesaver. 🙌

📧 Send email integration 📧

git-publish can call git-send-email(1) after creating a git tag. If there's a tag message, it'll be used as the cover letter. Send email 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.

You can override the stored per-branch subject prefix by providing the --subject-prefix parameter again, or to clear it permanently, 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.

You 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).

To have git-send-email add a cc list to individual patch emails we use:

$ git-publish --cc patches@example.org --send-email-args="--cc-cmd" --send-email-args="SCRIPT"

That's a lot of email magic. 💌

🧑‍💻 Creating profiles for frequently used projects 🧑‍💻

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. So CLI wins, always. 💪

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. Chef's kiss. 👨‍🍳💋

🚀 Sending pull requests 🚀

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

And that's how you slide into someone's DMs with a pull request. 💅

✨ CONFIGURATION ✨

okay bestie so there are three possible levels of configuration, and they have an order of precedence — like a lil hierarchy, and the little ones win over the big ones 💅

  1. Per-branch options only apply to a specific branch.
  2. Per-profile options apply when the profile is enabled with --profile.
  3. Global options apply in all cases.

Here's every config option you can set, no gatekeeping 🫶

  • branch.BRANCHNAME.gitpublishbase
  • gitpublishprofile.PROFILENAME.base
  • git-publish.base — same energy as the --base option 💖
  • branch.BRANCHNAME.gitpublishto
  • gitpublishprofile.PROFILENAME.to — same as the --to option
  • branch.BRANCHNAME.gitpublishcc
  • gitpublishprofile.PROFILENAME.cc — same as the --cc option
  • branch.BRANCHNAME.gitpublishcccmd
  • gitpublishprofile.PROFILENAME.gitpublishcccmd — same as the --cc-cmd option
  • gitpublishprofile.PROFILENAME.remote — the remote where the pull request tag will be pushed 📤
  • gitpublishprofile.PROFILENAME.message — same as the --message option
  • branch.BRANCHNAME.gitpublishprefix
  • gitpublishprofile.PROFILENAME.prefix — same as the --subject-prefix option
  • gitpublishprofile.PROFILENAME.suppresscc — same as the --suppress-cc option
  • gitpublishprofile.PROFILENAME.signoff — same as the --signoff option
  • gitpublishprofile.PROFILENAME.inspect-emails — same as the --inspect-emails option
  • gitpublishprofile.PROFILENAME.notes — same as the --notes option
  • gitpublishprofile.PROFILENAME.checkUrl
  • git-publish.checkUrl — same as the --no-check-url and --check-url options
  • gitpublishprofile.PROFILENAME.signPull
  • git-publish.signPull — same as the --no-sign-pull and --sign-pull options
  • git-publish.signingkey — same as the --keyid option

🪝 HOOKS 🪝

not me being obsessed with the fact that git-publish supports the githooks(5) mechanism for running user scripts at important points during the workflow 🦋

and like, the script can genuinely influence the outcome of the operation — for example, by rejecting a patch series that is about to be sent out. main character behaviour tbh 😤

Available hooks include:

  • pre-publish-send-email — invoked before git-send-email(1). Takes the path to the patches directory as an argument. If the exit code is non-zero, the series will not be sent 🚫
  • pre-publish-tag — invoked before creating the -staging tag on current branch. Takes one argument which refers to the base commit or branch. If the exit code is non-zero, git-publish will abort 💀

🌈 SEE ALSO 🌈

👑 AUTHOR 👑

Stefan Hajnoczi <mailto:stefanha@gmail.com>

Copyright (C) 2011-2018 Stefan Hajnoczi

and that's a wrap on the whole page bestie 💖 no cap, you're basically a git-publish expert now. this was version 1.8.2, dated 2025-07-23, and it's the GIT-PUBLISH(1) manual page — slay, go publish something iconic ✨🫶🌸

📦 where this page comes from