about summary refs log tree commit diff
path: root/third_party/git/Documentation/howto/new-command.txt
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/howto/new-command.txt')
-rw-r--r--third_party/git/Documentation/howto/new-command.txt106
1 files changed, 0 insertions, 106 deletions
diff --git a/third_party/git/Documentation/howto/new-command.txt b/third_party/git/Documentation/howto/new-command.txt
deleted file mode 100644
index 15a4c8031f..0000000000
--- a/third_party/git/Documentation/howto/new-command.txt
+++ /dev/null
@@ -1,106 +0,0 @@
-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 command-list.txt
-in the main directory.  If the new command is part of the typical Git
-workflow and you believe it common enough to be mentioned in 'git help',
-map this command to a common group in the column [common].
-
-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.