--- 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html