GitGitGadget is a tool created by
Johannes Schindelin to make life as a Git contributor easier for those used to
the GitHub PR workflow. It allows contributors to open pull requests against its
mirror of the Git project, and does some magic to turn the PR into a set of
emails and send them out for you. It also runs the Git continuous integration
suite for you. It's documented at https://gitgitgadget.github.io/.

[[create-fork]]
=== Forking `git/git` on GitHub

Before you can send your patch off to be reviewed using GitGitGadget, you will
need to fork the Git project and upload your changes. First thing - make sure
you have a GitHub account.

Head to the https://github.com/git/git[GitHub mirror] and look for the Fork
button. Place your fork wherever you deem appropriate and create it.

[[upload-to-fork]]
=== Uploading to Your Own Fork

To upload your branch to your own fork, you'll need to add the new fork as a
remote. You can use `git remote -v` to show the remotes you have added already.
From your new fork's page on GitHub, you can press "Clone or download" to get
the URL; then you need to run the following to add, replacing your own URL and
remote name for the examples provided:

----
$ git remote add remotename git@github.com:remotename/git.git
----

or to use the HTTPS URL:

----
$ git remote add remotename https://github.com/remotename/git/.git
----

Run `git remote -v` again and you should see the new remote showing up.
`git fetch remotename` (with the real name of your remote replaced) in order to
get ready to push.

Next, double-check that you've been doing all your development in a new branch
by running `git branch`. If you didn't, now is a good time to move your new
commits to their own branch.

As mentioned briefly at the beginning of this document, we are basing our work
on `master`, so go ahead and update as shown below, or using your preferred
workflow.

----
$ git checkout master
$ git pull -r
$ git rebase master psuh
----

Finally, you're ready to push your new topic branch! (Due to our branch and
command name choices, be careful when you type the command below.)

----
$ git push remotename psuh
----

Now you should be able to go and check out your newly created branch on GitHub.

[[send-pr-ggg]]
=== Sending a PR to GitGitGadget

In order to have your code tested and formatted for review, you need to start by
opening a Pull Request against `gitgitgadget/git`. Head to
https://github.com/gitgitgadget/git and open a PR either with the "New pull
request" button or the convenient "Compare & pull request" button that may
appear with the name of your newly pushed branch.

Review the PR's title and description, as they're used by GitGitGadget
respectively as the subject and body of the cover letter for your change. Refer
to <<cover-letter,"The cover letter">> above for advice on how to title your
submission and what content to include in the description.

NOTE: For single-patch contributions, your commit message should already be
meaningful and explain at a high level the purpose (what is happening and why)
of your patch, so you usually do not need any additional context. In that case,
remove the PR description that GitHub automatically generates from your commit
message (your PR description should be empty). If you do need to supply even
more context, you can do so in that space and it will be appended to the email
that GitGitGadget will send, between the three-dash line and the diffstat
(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once
submitted).

When you're happy, submit your pull request.

[[run-ci-ggg]]
=== Running CI and Getting Ready to Send

If it's your first time using GitGitGadget (which is likely, as you're using
this tutorial) then someone will need to give you permission to use the tool.
As mentioned in the GitGitGadget documentation, you just need someone who
already uses it to comment on your PR with `/allow <username>`. GitGitGadget
will automatically run your PRs through