[PATCH] Add documentation on how to integrate commands.

[esr@thyrsus.com (Eric S. Raymond)]

---
 Documentation/CommandIntegration |   69 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 Documentation/CommandIntegration

diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration
new file mode 100644
index 0000000..be248f7
--- /dev/null
+++ b/Documentation/CommandIntegration
@@ -0,0 +1,69 @@
+= Integrating new subcommands =
+
+This is how-to documentation for people who want to add extension
+commands to git.
+
+== Runtime environment ==
+
+git subcommands are standalone executables that live in the git
+execution directory, normally /usr/lib/git-core.  The git executable itself
+is a thin wrapper that sets GIT_DIR and passes command-line arguments
+to the subcommand.
+
+(If "git foo" is not found in the git execution directory, the wrapper
+will look in the rest of your $PATH for it.  Thus, it's possible
+to write local git extensions that don't live in system space.)
+
+== Implementation languages ==
+
+Most subcommands are written in C or shell.  A few are written in
+Perl.  A tiny minority are written in Python.
+
+While we strongly encourage coding in portable C for portability, these
+specific scripting languages are also acceptable. We won't accept more
+without a very strong technical case, as we don't want to broaden the
+git suite's required dependencies.
+
+C commands are normally written as single modules, named after the
+command, that link a core library called libgit.  Thus, your command
+'git-foo' would normally be implemented as a single "git-foo.c"; this
+organization makes it easy for people reading the code to find things.
+
+See the CodingGuidelines document for other guidance on what we consider
+good practice in C and shell.
+
+== What every extension command needs ==
+
+You must have a man page, written in asciidoc (this is what git help
+followed by your subcommand name will display).  Be aware that there is
+a local asciidoc configuration and macros which you should use.  It's
+often helpful to start by cloning an existing page and replacing the
+text content.
+
+You must have a test, written to report in TAP (Test Anything Protocol).
+Tests are executables (usually shell scripts) that live in the 't' 
+subdirectory of the tree.  Each test name begins with 't' and a sequence
+number that controls where in the test sequence it will be executed;
+conventionally the rest of the name stem is that of the command 
+being tested.
+
+If your test requires an example repository, create it yourself in the
+test script.  There is a test library of shell functions that assists
+wit this; when you use it, the environment is set in a predictable way
+so the author, committer and timestamps are all set to a single well
+known value, allowing git to create a commit that is reproducible on
+all platforms. A test_tick function is used in the scripts to move the
+clock, allowing different times to be used. For an example see
+t7502-commit.sh, or really any script in that directory.
+
+== Integrating a command ==
+
+Here are the things you need to do when you want to merge a new 
+subcommand into the git tree.
+
+1. Append your command name to one of the variables BUILTIN_OBJS,
+EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
+
+2. Drop its test in the t directory.
+
+That's all there is to it.
-- 
1.7.9.5



-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

The same applies for other kinds of long-lasting low-level pain. [...]
The body's response to being jabbed, pierced, and cut is to produce
endorphins. [...]  So here's my programme for breaking that cycle of
dependency on Windows: get left arm tattooed with dragon motif, buy a
crate of Jamaican Hot! Pepper Sauce, get nipples pierced.  With any
luck that will produce enough endorphins to make Windows completely
redundant, and I can then upgrade to Linux and get on with things.
	-- Pieter Hintjens