{"thread":{"id":"32188","subject":"[PATCH] Add documentation on how to integrate commands.","startedAt":"2012-11-24T12:23:33Z","lastAt":"2012-11-26T05:25:00Z","messageCount":8,"participants":["Eric S. Raymond","Pete Wyckoff","Michael Haggerty","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"203765","messageId":"20121124122333.BAD7B4065F@snark.thyrsus.com","threadId":"32188","inReplyTo":null,"subject":"[PATCH] Add documentation on how to integrate commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-24T12:23:33Z","receivedAt":"2012-11-24T12:23:33Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"---\n Documentation/CommandIntegration | 69 ++++++++++++++++++++++++++++++++++++++\n 1 file changed, 69 insertions(+)\n create mode 100644 Documentation/CommandIntegration\n\ndiff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration\nnew file mode 100644\nindex 0000000..be248f7\n--- /dev/null\n+++ b/Documentation/CommandIntegration\n@@ -0,0 +1,69 @@\n+= Integrating new subcommands =\n+\n+This is how-to documentation for people who want to add extension\n+commands to git.\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.\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+If your test requires an example repository, create it yourself in the\n+test script. There is a test library of shell functions that assists\n+wit this; when you use it, the environment is set in a predictable way\n+so the author, committer and timestamps are all set to a single well\n+known value, allowing git to create a commit that is reproducible on\n+all platforms. A test_tick function is used in the scripts to move the\n+clock, allowing different times to be used. For an example see\n+t7502-commit.sh, or really any script in that directory.\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+That's all there is to it.\n-- \n1.7.9.5\n\n\n\n-- \n\t\tEric S. Raymond\n\nThe same applies for other kinds of long-lasting low-level pain. [...]\nThe body's response to being jabbed, pierced, and cut is to produce\nendorphins. [...] So here's my programme for breaking that cycle of\ndependency on Windows: get left arm tattooed with dragon motif, buy a\ncrate of Jamaican Hot! Pepper Sauce, get nipples pierced. With any\nluck that will produce enough endorphins to make Windows completely\nredundant, and I can then upgrade to Linux and get on with things.\n\t-- Pieter Hintjens\n"},{"id":"203766","messageId":"20121124151127.GA24459@padd.com","threadId":"32188","inReplyTo":"20121124122333.BAD7B4065F@snark.thyrsus.com","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Pete Wyckoff","fromEmail":"pw@padd.com","sentAt":"2012-11-24T15:11:27Z","receivedAt":"2012-11-24T15:11:27Z","isPatch":true,"sender":{"key":"pw@padd.com","avatar":null},"body":"esr@thyrsus.com wrote on Sat, 24 Nov 2012 07:23 -0500:\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> +That's all there is to it.\n\nNice start. A few other details; I recently did this for git-p4\n(python).\n\n.gitignore: ignore the auto-generated script, e.g. when\ngit-foo.py is built into git-foo.\n\nINSTALL: note language requirements if odd (see python section)\n\ncommand-list.txt: categorization of commands for git(1) etc.\n\nRelNotes: Junio generally does this.\n\n\nAlso please read Documentation/technical/api-builtin.txt to\nsee how to add a built-in command. It also has comments that\nare identical for both built-in and stand-alone command. Could\nbe that your text would better go near or with that one, as perhaps\napi-command.txt.\n\n\t\t-- Pete\n"},{"id":"203767","messageId":"20121124152309.GA31679@thyrsus.com","threadId":"32188","inReplyTo":"20121124151127.GA24459@padd.com","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-24T15:23:09Z","receivedAt":"2012-11-24T15:23:09Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Pete Wyckoff :\n> Nice start. A few other details; I recently did this for git-p4\n> (python).\n> \n> .gitignore: ignore the auto-generated script, e.g. when\n> git-foo.py is built into git-foo.\n> \n> INSTALL: note language requirements if odd (see python section)\n> \n> command-list.txt: categorization of commands for git(1) etc.\n> \n> RelNotes: Junio generally does this.\n> \n> \n> Also please read Documentation/technical/api-builtin.txt to\n> see how to add a built-in command. It also has comments that\n> are identical for both built-in and stand-alone command. Could\n> be that your text would better go near or with that one, as perhaps\n> api-command.txt.\n\nGood points. I will submit a revised patch later today.\n-- \n\t\tEric S. Raymond\n"},{"id":"203771","messageId":"20121125000605.GA22548@thyrsus.com","threadId":"32188","inReplyTo":"20121124151127.GA24459@padd.com","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-25T00:06:05Z","receivedAt":"2012-11-25T00:06:05Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Working on my revised patch...\n\nPete Wyckoff :\n> Nice start. A few other details; I recently did this for git-p4\n> (python).\n> \n> .gitignore: ignore the auto-generated script, e.g. when\n> git-foo.py is built into git-foo.\n\nAdded:\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> INSTALL: note language requirements if odd (see python section)\n\nAdded:\n\n 4. If your command has dependency on a particular version, document\n it in the INSTALL file.\n \n> command-list.txt: categorization of commands for git(1) etc.\n\nAre the values in the right-hand column documented somewhere? What\nuses them, and for what purposes.\n \n> RelNotes: Junio generally does this.\n\nAdded:\n\n 6. When your patch is merged, remind the maintainer to add something\n about it in the RelNotes file.\n \n> Also please read Documentation/technical/api-builtin.txt to\n> see how to add a built-in command. It also has comments that\n> are identical for both built-in and stand-alone command. Could\n> be that your text would better go near or with that one, as perhaps\n> api-command.txt.\n\nI think this is a good suggestion and will implement it.\n\nIf someone can explain the values used in command-list.txt, or (better) point\nme to documentation of them, that will enable me to finish the revised patch.\n-- \n\t\tEric S. Raymond\n"},{"id":"203778","messageId":"50B1C4E3.9070500@alum.mit.edu","threadId":"32188","inReplyTo":"20121124122333.BAD7B4065F@snark.thyrsus.com","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2012-11-25T07:12:35Z","receivedAt":"2012-11-25T07:12:35Z","isPatch":true,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 11/24/2012 01:23 PM, Eric S. Raymond wrote:\n> ---\n> Documentation/CommandIntegration | 69 ++++++++++++++++++++++++++++++++++++++\n> 1 file changed, 69 insertions(+)\n> create mode 100644 Documentation/CommandIntegration\n> \n> diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration\n> new file mode 100644\n> index 0000000..be248f7\n> --- /dev/null\n> +++ b/Documentation/CommandIntegration\n> @@ -0,0 +1,69 @@\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> +If your test requires an example repository, create it yourself in the\n> +test script. There is a test library of shell functions that assists\n> +wit this; when you use it, the environment is set in a predictable way\n> +so the author, committer and timestamps are all set to a single well\n> +known value, allowing git to create a commit that is reproducible on\n> +all platforms. A test_tick function is used in the scripts to move the\n> +clock, allowing different times to be used. For an example see\n> +t7502-commit.sh, or really any script in that directory.\n\nI think that here a reference to the file t/README would help (and\nperhaps make part of your text redundant).\n\nMichael\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"203779","messageId":"20121125082915.GA17626@thyrsus.com","threadId":"32188","inReplyTo":"50B1C4E3.9070500@alum.mit.edu","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-25T08:29:16Z","receivedAt":"2012-11-25T08:29:16Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Michael Haggerty :\n> I think that here a reference to the file t/README would help (and\n> perhaps make part of your text redundant).\n\nThank you, done.\n-- \n\t\tEric S. Raymond\n"},{"id":"203848","messageId":"7vy5hpvukk.fsf@alter.siamese.dyndns.org","threadId":"32188","inReplyTo":"20121124122333.BAD7B4065F@snark.thyrsus.com","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-26T04:47:55Z","receivedAt":"2012-11-26T04:47:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"esr@thyrsus.com (Eric S. Raymond) writes:\n\n> ---\n\nSign off?\n\n> Documentation/CommandIntegration | 69 ++++++++++++++++++++++++++++++++++++++\n> 1 file changed, 69 insertions(+)\n> create mode 100644 Documentation/CommandIntegration\n>\n> diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration\n> new file mode 100644\n> index 0000000..be248f7\n> --- /dev/null\n> +++ b/Documentation/CommandIntegration\n> @@ -0,0 +1,69 @@\n> += Integrating new subcommands =\n> +\n> +This is how-to documentation for people who want to add extension\n> +commands to git.\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\nAs the first sentence in this paragraph does not make it clear\nenough that you are defining a new term \"git execution directory\",\n\"execution directory\" here may be misleading and can easily be\nmistaken as if we look something in the directory where the user\nruns \"git\" in. We usually call it \"exec path\".\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\nActually, we tend to avoid Python dependency for anything important\nand allow it only on fringes; people who lack Python environment are\nnot missing much, and we would want to keep it that way until the\nsituation on the Windows front changes.\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\nI would prefer to see this sentence not call libgit.a a \"library\".\nWe primarily use libgit.a to let linker pick necessary object files\nwithout us having to list object files for non-builtin command\nimplementations and it is not designed to be used by other people.\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> +That's all there is to it.\n\nAnd when sending a patch in, do not forget to sign off your patches\n;-)\n"},{"id":"203855","messageId":"20121126052500.GA15605@thyrsus.com","threadId":"32188","inReplyTo":"7vy5hpvukk.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Add documentation on how to integrate commands.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-11-26T05:25:00Z","receivedAt":"2012-11-26T05:25:00Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Junio C Hamano :\n> As the first sentence in this paragraph does not make it clear\n> enough that you are defining a new term \"git execution directory\",\n> \"execution directory\" here may be misleading and can easily be\n> mistaken as if we look something in the directory where the user\n> runs \"git\" in. We usually call it \"exec path\".\n\nFixed.\n\n> Actually, we tend to avoid Python dependency for anything important\n> and allow it only on fringes; people who lack Python environment are\n> not missing much, and we would want to keep it that way until the\n> situation on the Windows front changes.\n\nAdded:\n\n Python is fine for import utilities, surgical tools, remote helpers\n and other code at the edges of the git suite - but it should not yet\n be used for core functions. This may change in the future; the problem\n is that we need better Python integration in the git Windows installer\n before we can be confident people in that environment won't\n experience an unacceptably large loss of capability.\n\nI will also take this as a part-resolution of the related policy thread. \nIssue perhaps to be revisited when the Windows port gets the Python support\nto a good state.\n\nI will submit for separate consideration a patch proposing the following\nnew guidelines:\n\n1. Python code SHOULD NOT require an interpreter version newer than 2.6.\n\n2. Python code SHOULD check the interpreter version and exit gracefully\n with an explanation if it detects that its dependency cannot be satisfied.\n\n> I would prefer to see this sentence not call libgit.a a \"library\".\n> We primarily use libgit.a to let linker pick necessary object files\n> without us having to list object files for non-builtin command\n> implementations and it is not designed to be used by other people.\n\nFixed. I now refer to it as a \"collection of functions\".\n\n> And when sending a patch in, do not forget to sign off your patches\n> ;-)\n\nAdded. I will submit a third time with a signoff. :-)\n-- \n\t\tEric S. Raymond\n"}]}