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 work on the `master`
branch of the upstream project. Create the `psuh` branch you will use for
development like so:

----
$ git checkout -b psuh origin/master
----

We'll make a number of commits here in order to demonstrate how to send a topic
with multiple patches up for review simultaneously.

[[code-it-up]]
== Code It Up!

NOTE: A reference implementation can be found at
https://github.com/nasamuffin/git/tree/psuh.

[[add-new-command]]
=== Adding a New Command

Lots of the subcommands are written as builtins, which means they are
implemented in C and compiled into the main `git` executable. Implementing the
very simple `psuh` command as a built-in will demonstrate the structure of the
codebase, the internal API, and the process of working together as a contributor
with the reviewers and maintainer to integrate this change into the system.

Built-in subcommands are typically implemented in a function named "cmd_"
followed by the name of the subcommand, in a source file named after the
subcommand and contained within `builtin/`. So it makes sense to implement your
command in `builtin/psuh.c`. Create that file, and within it, write the entry
point for your command in a function matching the style and signature:

----
int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
	     const char *prefix UNUSED, struct repository *repo UNUSED)
----

A few things to note:

* A subcommand implementation takes its command line arguments
  in `int argc` + `const char **argv`, like `main()` would.

* It also takes two extra parameters, `prefix` and `repo`. What
  they mean will not be discussed until much later.

* Because this first example will not use any of the parameters,
  your compiler will give warnings on unused parameters. As the
  list of these four parameters is mandated by the API to add
  new built-in commands, you cannot omit them. Instead, you add
  `UNUSED` to each of them to tell the compiler that you *know*
  you are not (yet) using it.

We'll also need to add the declaration of psuh; open up `builtin.h`, find the
declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
in order to keep the declarations alphabetically sorted:

----
int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
----

Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
`#include "gettext.h"` to use functions related to printing output text.

Go ahead and add some throwaway printf to the `cmd_psuh` function. This is a
decent starting point as we can now add build rules and register the command.

NOTE: Your throwaway text, as well as much of the text you will be adding over
the course of this tutorial, is user-facing. That means it needs to be
localizable. Take a look at `po/README` under "Marking strings for translation".
Throughout the tutorial, we will mark strings for translation as necessary; you
should also do so when writing your user-facing commands in the future.

----
int cmd_psuh(int