[PATCH] Add documentation on how to integrate commands.

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

esr@thyrsus.com wrote on Sat, 24 Nov 2012 07:23 -0500:

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

Nice start.  A few other details; I recently did this for git-p4
(python).

.gitignore: ignore the auto-generated script, e.g. when
git-foo.py is built into git-foo.

INSTALL: note language requirements if odd (see python section)

command-list.txt: categorization of commands for git(1) etc.

RelNotes: Junio generally does this.


Also please read Documentation/technical/api-builtin.txt to
see how to add a built-in command.  It also has comments that
are identical for both built-in and stand-alone command.  Could
be that your text would better go near or with that one, as perhaps
api-command.txt.

		-- Pete

Pete Wyckoff [off-list ref]:

Nice start.  A few other details; I recently did this for git-p4
(python).

.gitignore: ignore the auto-generated script, e.g. when
git-foo.py is built into git-foo.

INSTALL: note language requirements if odd (see python section)

command-list.txt: categorization of commands for git(1) etc.

RelNotes: Junio generally does this.


Also please read Documentation/technical/api-builtin.txt to
see how to add a built-in command.  It also has comments that
are identical for both built-in and stand-alone command.  Could
be that your text would better go near or with that one, as perhaps
api-command.txt.

Good points.  I will submit a revised patch later today.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Working on my revised patch...

Pete Wyckoff [off-list ref]:

Nice start.  A few other details; I recently did this for git-p4
(python).

.gitignore: ignore the auto-generated script, e.g. when
git-foo.py is built into git-foo.

Added:

    3. If your command is implemented in an interpreted language with a 
    p-code intermediate form, make sure .gitignore in the main directory
    includes a pattern entry that ignores such files.  Python .pyc and
    .pyo files will already be covered.

INSTALL: note language requirements if odd (see python section)

Added:

    4. If your command has dependency on a particular version, document
    it in the INSTALL file.
 

command-list.txt: categorization of commands for git(1) etc.

Are the values in the right-hand column documented somewhere?  What
uses them, and for what purposes.
 

RelNotes: Junio generally does this.

Added:

    6. When your patch is merged, remind the maintainer to add something
    about it in the RelNotes file.
 

Also please read Documentation/technical/api-builtin.txt to
see how to add a built-in command.  It also has comments that
are identical for both built-in and stand-alone command.  Could
be that your text would better go near or with that one, as perhaps
api-command.txt.

I think this is a good suggestion and will implement it.

If someone can explain the values used in command-list.txt, or (better) point
me to documentation of them, that will enable me to finish the revised patch.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

On 11/24/2012 01:23 PM, Eric S. Raymond wrote:

I think that here a reference to the file t/README would help (and
perhaps make part of your text redundant).

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

Michael Haggerty [off-list ref]:

I think that here a reference to the file t/README would help (and
perhaps make part of your text redundant).

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