Provided by: git-publish_1.8.1-1_all bug

NAME

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

SYNOPSIS

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

DESCRIPTION

       git-publish prepares patches and stores them as git tags for future reference.  It works
       with individual patches as well as patch series.  Revision numbering is handled
       automatically.

       No constraints are placed on git workflow, both vanilla git commands and custom workflow
       scripts are compatible with git-publish.

       Email sending and pull requests are fully integrated so that publishing patches can be
       done in a single command.

       Hook scripts are invoked during patch preparation so that custom checks or test runs can
       be automated.

OPTIONS

       --version
           Show program's version number and exit.

       -h
       --help
           Show help message and exit.

       --annotate
           Review and edit each patch email.

       -b BASE
       --base=BASE
           Branch which this is based off (defaults to master).

       --cc=CC
           Specify a Cc: email recipient.

       --cc-cmd=CC_CMD
           Specify a command add whose output to add the Cc: email recipient list.  See
           git-send-email(1) for details.

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

       --edit
           Edit message but do not tag a new version.  Use this to draft the cover letter before
           actually tagging a new version.

       --no-inspect-emails
           Do not prompt for confirmation before sending emails.

       --inspect-emails
           Show confirmation before sending emails.

       -n NUMBER
       --number=NUMBER
           Explicitly specify the version number (auto-generated by default).

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

       -p PROFILE_NAME
       --profile=PROFILE_NAME
           Select default settings from the given profile.

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

       --setup
           Add git alias in ~/.gitconfig so that the "git publish" git sub-command works.

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

       --forget-cc
           Forget all previous Cc: email addresses.

       --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 cover letter (or the single patch).

DISCUSSION

   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.

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

       Overriding the version number

       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.

       Overriding the branch name

       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'.

   Tag messages
       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).

       Editing tag messages without publishing

       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.

   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 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

   Send email integration
       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).

   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.

       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.

   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

CONFIGURATION

       There are three possible levels of configuration with the following order of precedence:

       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.

       The following configuration options are available:

       branch.BRANCHNAME.gitpublishbase
       gitpublishprofile.PROFILENAME.base
       git-publish.base
           Same 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

       git-publish supports the githooks(5) mechanism for running user scripts at important
       points during the workflow.  The script can influence the outcome of the operation, for
       example, by rejecting a patch series that is about to be sent out.

       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

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

AUTHOR

       Stefan Hajnoczi <mailto:stefanha@gmail.com>

COPYRIGHT

       Copyright (C) 2011-2018 Stefan Hajnoczi