{"thread":{"id":"32195","subject":"[PATCH] Document the integration requirements for extension commands.","startedAt":"2012-11-25T21:35:26Z","lastAt":"2012-11-25T21:35:26Z","messageCount":1,"participants":["Eric S. Raymond"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"203824","messageId":"20121125213526.A708A4065F@snark.thyrsus.com","threadId":"32195","inReplyTo":null,"subject":"[PATCH] Document the integration requirements for extension commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-25T21:35:26Z","receivedAt":"2012-11-25T21:35:26Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"This contains no policy changes or proposals, it simply attempts\nto document the interfaces and conventions already in place.\n---\n Documentation/technical/api-command.txt |   81 +++++++++++++++++++++++++++++++\n 1 file changed, 81 insertions(+)\n create mode 100644 Documentation/technical/api-command.txt\n\ndiff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt\nnew file mode 100644\nindex 0000000..de76614\n--- /dev/null\n+++ b/Documentation/technical/api-command.txt\n@@ -0,0 +1,81 @@\n+= Integrating new subcommands =\n+\n+This is how-to documentation for people who want to add extension\n+commands to git.  It should be read alongside api-builtin.txt.\n+\n+== Runtime environment ==\n+\n+git subcommands are standalone executables that live in the git\n+execution directory, normally /usr/lib/git-core.  The git executable itself\n+is a thin wrapper that sets GIT_DIR and passes command-line arguments\n+to the subcommand.\n+\n+(If \"git foo\" is not found in the git execution directory, the wrapper\n+will look in the rest of your $PATH for it.  Thus, it's possible\n+to write local git extensions that don't live in system space.)\n+\n+== Implementation languages ==\n+\n+Most subcommands are written in C or shell.  A few are written in\n+Perl.  A tiny minority are written in Python.\n+\n+While we strongly encourage coding in portable C for portability, these\n+specific scripting languages are also acceptable. We won't accept more\n+without a very strong technical case, as we don't want to broaden the\n+git suite's required dependencies.\n+\n+C commands are normally written as single modules, named after the\n+command, that link a core library called libgit.  Thus, your command\n+'git-foo' would normally be implemented as a single \"git-foo.c\"; this\n+organization makes it easy for people reading the code to find things.\n+\n+See the CodingGuidelines document for other guidance on what we consider\n+good practice in C and shell, and api-builtin.txt for the support\n+functions available to built-in commands written in C.\n+\n+== What every extension command needs ==\n+\n+You must have a man page, written in asciidoc (this is what git help\n+followed by your subcommand name will display).  Be aware that there is\n+a local asciidoc configuration and macros which you should use.  It's\n+often helpful to start by cloning an existing page and replacing the\n+text content.\n+\n+You must have a test, written to report in TAP (Test Anything Protocol).\n+Tests are executables (usually shell scripts) that live in the 't' \n+subdirectory of the tree.  Each test name begins with 't' and a sequence\n+number that controls where in the test sequence it will be executed;\n+conventionally the rest of the name stem is that of the command \n+being tested.\n+\n+Read the file t/README to learn more about the conventions to be used\n+in writing tests, and the test support library.\n+\n+== Integrating a command ==\n+\n+Here are the things you need to do when you want to merge a new \n+subcommand into the git tree.\n+\n+1. Append your command name to one of the variables BUILTIN_OBJS,\n+EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.\n+\n+2. Drop its test in the t directory.\n+\n+3. If your command is implemented in an interpreted language with a \n+p-code intermediate form, make sure .gitignore in the main directory\n+includes a pattern entry that ignores such files.  Python .pyc and\n+.pyo files will already be covered.\n+\n+4. If your command has any dependency on a a particular version of\n+your language, document it in the INSTALL file.\n+\n+5. There is a file command-list.txt in the distribution main directory\n+that categorizes commands by type, so they can be listed in appropriate\n+subsections in the documentation's summary command list.  Add an entry \n+for yours.  To understand the categories, look at git-cmmands.txt\n+in the main directory.\n+\n+6. When your patch is merged, remind the maintainer to add something\n+about it in the RelNotes file.\n+\n+That's all there is to it.\n-- \n1.7.9.5\n\n\n\n-- \n\t\t<a href=\"http://www.catb.org/~esr/\">Eric S. Raymond</a>\n\n\"Rightful liberty is unobstructed action, according to our will, within limits\ndrawn around us by the equal rights of others.\"\n\t-- Thomas Jefferson\n"}]}