Move ./technical/api-command.txt to ./howto/new-command.txt
authorThomas Ackermann <th.acker@arcor.de>
Fri, 21 Dec 2012 18:05:28 +0000 (19:05 +0100)
committerJunio C Hamano <gitster@pobox.com>
Fri, 21 Dec 2012 18:35:53 +0000 (10:35 -0800)
The contents of this document does not describe any particular API, but
is more about the way to add a new command, which belongs to the "How To"
section of the documentation suite.

Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/Makefile
Documentation/howto/new-command.txt [new file with mode: 0644]
Documentation/technical/api-command.txt [deleted file]
index 361550422a6e180f5614305985cfd12aa964ffe0..5243222f136b6dff8a4ca22a4c5e78b0f72bac90 100644 (file)
@@ -21,6 +21,7 @@ ARTICLES += git-tools
 ARTICLES += git-bisect-lk2009
 # with their own formatting rules.
 SP_ARTICLES = user-manual
+SP_ARTICLES += howto/new-command
 SP_ARTICLES += howto/revert-branch-rebase
 SP_ARTICLES += howto/using-merge-subtree
 SP_ARTICLES += howto/using-signed-tag-in-pull-request
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
new file mode 100644 (file)
index 0000000..36502f6
--- /dev/null
@@ -0,0 +1,104 @@
+From: Eric S. Raymond <esr@thyrsus.com>
+Abstract: This is how-to documentation for people who want to add extension
+ commands to git.  It should be read alongside api-builtin.txt.
+Content-type: text/asciidoc
+
+How to integrate new subcommands
+================================
+
+This is how-to documentation for people who want to add extension
+commands to git.  It should be read alongside api-builtin.txt.
+
+Runtime environment
+-------------------
+
+git subcommands are standalone executables that live in the git exec
+path, normally /usr/lib/git-core.  The git executable itself is a
+thin wrapper that knows where the subcommands live, and runs them by
+passing command-line arguments to them.
+
+(If "git foo" is not found in the git exec path, 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.
+
+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.  Import utilities,
+surgical tools, remote helpers and other code at the edges of the
+git suite are more lenient and we allow Python (and even Tcl/tk),
+but they should not be used for core functions.
+
+This may change in the future.  Especially Python is not allowed in
+core because we need better Python integration in the git Windows
+installer before we can be confident people in that environment
+won't experience an unacceptably large loss of capability.
+
+C commands are normally written as single modules, named after the
+command, that link a collection of functions called libgit.  Thus,
+your command 'git-foo' would normally be implemented as a single
+"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main
+binary); 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, and api-builtin.txt for the support
+functions available to built-in commands written in C.
+
+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.
+
+Read the file t/README to learn more about the conventions to be used
+in writing tests, and the test support library.
+
+Integrating a command
+---------------------
+
+Here are the things you need to do when you want to merge a new
+subcommand into the git tree.
+
+1. Don't forget to sign off your patch!
+
+2. Append your command name to one of the variables BUILTIN_OBJS,
+EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
+
+3. Drop its test in the t directory.
+
+4. 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.
+
+5. If your command has any dependency on a particular version of
+your language, document it in the INSTALL file.
+
+6. There is a file command-list.txt in the distribution main directory
+that categorizes commands by type, so they can be listed in appropriate
+subsections in the documentation's summary command list.  Add an entry
+for yours.  To understand the categories, look at git-cmmands.txt
+in the main directory.
+
+7. Give the maintainer one paragraph to include in the RelNotes file
+to describe the new feature; a good place to do so is in the cover
+letter [PATCH 0/n].
+
+That's all there is to it.
diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt
deleted file mode 100644 (file)
index d3b9781..0000000
+++ /dev/null
@@ -1,99 +0,0 @@
-Integrating new subcommands
-===========================
-
-This is how-to documentation for people who want to add extension
-commands to git.  It should be read alongside api-builtin.txt.
-
-Runtime environment
--------------------
-
-git subcommands are standalone executables that live in the git exec
-path, normally /usr/lib/git-core.  The git executable itself is a
-thin wrapper that knows where the subcommands live, and runs them by
-passing command-line arguments to them.
-
-(If "git foo" is not found in the git exec path, 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.
-
-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.  Import utilities,
-surgical tools, remote helpers and other code at the edges of the
-git suite are more lenient and we allow Python (and even Tcl/tk),
-but they should not be used for core functions.
-
-This may change in the future.  Especially Python is not allowed in
-core because we need better Python integration in the git Windows
-installer before we can be confident people in that environment
-won't experience an unacceptably large loss of capability.
-
-C commands are normally written as single modules, named after the
-command, that link a collection of functions called libgit.  Thus,
-your command 'git-foo' would normally be implemented as a single
-"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main
-binary); 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, and api-builtin.txt for the support
-functions available to built-in commands written in C.
-
-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.
-
-Read the file t/README to learn more about the conventions to be used
-in writing tests, and the test support library.
-
-Integrating a command
----------------------
-
-Here are the things you need to do when you want to merge a new
-subcommand into the git tree.
-
-1. Don't forget to sign off your patch!
-
-2. Append your command name to one of the variables BUILTIN_OBJS,
-EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
-
-3. Drop its test in the t directory.
-
-4. 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.
-
-5. If your command has any dependency on a particular version of
-your language, document it in the INSTALL file.
-
-6. There is a file command-list.txt in the distribution main directory
-that categorizes commands by type, so they can be listed in appropriate
-subsections in the documentation's summary command list.  Add an entry
-for yours.  To understand the categories, look at git-cmmands.txt
-in the main directory.
-
-7. Give the maintainer one paragraph to include in the RelNotes file
-to describe the new feature; a good place to do so is in the cover
-letter [PATCH 0/n].
-
-That's all there is to it.