My First Contribution to the Git Project
========================================
:sectanchors:

[[summary]]
== Summary

This is a tutorial demonstrating the end-to-end workflow of creating a change to
the Git tree, sending it for review, and making changes based on comments.

[[prerequisites]]
=== Prerequisites

This tutorial assumes you're already fairly familiar with using Git to manage
source code.  The Git workflow steps will largely remain unexplained.

[[related-reading]]
=== Related Reading

This tutorial aims to summarize the following documents, but the reader may find
useful additional context:

- `Documentation/SubmittingPatches`
- `Documentation/howto/new-command.adoc`

[[getting-help]]
=== Getting Help

If you get stuck, you can seek help in the following places.

==== git@vger.kernel.org

This is the main Git project mailing list where code reviews, version
announcements, design discussions, and more take place. Those interested in
contributing are welcome to post questions here. The Git list requires
plain-text-only emails and prefers inline and bottom-posting when replying to
mail; you will be CC'd in all replies to you. Optionally, you can subscribe to
the list by sending an email to <git+subscribe@vger.kernel.org>
(see https://subspace.kernel.org/subscribing.html for details).
The https://lore.kernel.org/git[archive] of this mailing list is
available to view in a browser.

==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat

This IRC channel is for conversations between Git contributors. If someone is
currently online and knows the answer to your question, you can receive help
in real time. Otherwise, you can read the
https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see
whether someone answered you. IRC does not allow offline private messaging, so
if you try to private message someone and then log out of IRC, they cannot
respond to you. It's better to ask your questions in the channel so that you
can be answered if you disconnect and so that others can learn from the
conversation.

[[getting-started]]
== Getting Started

[[cloning]]
=== Clone the Git Repository

Git is mirrored in a number of locations. Clone the repository from one of them;
https://git-scm.com/downloads suggests one of the best places to clone from is
the mirror on GitHub.

----
$ git clone https://github.com/git/git git
$ cd git
----

[[dependencies]]
=== Installing Dependencies

To build Git from source, you need to have a handful of dependencies installed
on your system. For a hint of what's needed, you can take a look at
`INSTALL`, paying close attention to the section about Git's dependencies on
external programs and libraries. That document mentions a way to "test-drive"
our freshly built Git without installing; that's the method we'll be using in
this tutorial.

Make sure that your environment has everything you need by building your brand
new clone of Git from the above step:

----
$ make
----

NOTE: The Git build is parallelizable. `-j#` is not included above but you can
use it as you prefer, here and elsewhere.

[[identify-problem]]
=== Identify Problem to Solve

////
Use + to indicate fixed-width here; couldn't get ` to work nicely with the
quotes around "Pony Saying 'Um, Hello'".
////
In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying
`Um, Hello''' - a feature which has gone unimplemented despite a high frequency
of invocation during users' typical daily workflow.

(We've seen some other effort in this space with the implementation of popular
commands such as `sl`.)

[[setup-workspace]]
=== Set Up Your Workspace

Let's start by making a development branch to work on our changes. Per
`Documentation/SubmittingPatches`, since a brand new command is a new feature,
it's fine to base your work on `master`. However, in the future for bugfixes,
etc., you should check that document and base it on the appropriate branch.

For the purposes of this document, we will base all our