Re: [PATCH] Add documentation on how to integrate commands.
Michael Haggerty mhag...@alum.mit.edu: I think that here a reference to the file t/README would help (and perhaps make part of your text redundant). Thank you, done. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add documentation on how to integrate commands.
e...@thyrsus.com (Eric S. Raymond) writes: --- Sign off? 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 000..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 As the first sentence in this paragraph does not make it clear enough that you are defining a new term git execution directory, execution directory here may be misleading and can easily be mistaken as if we look something in the directory where the user runs git in. We usually call it exec path. +== 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. Actually, we tend to avoid Python dependency for anything important and allow it only on fringes; people who lack Python environment are not missing much, and we would want to keep it that way until the situation on the Windows front changes. +C commands are normally written as single modules, named after the +command, that link a core library called libgit. Thus, your command I would prefer to see this sentence not call libgit.a a library. We primarily use libgit.a to let linker pick necessary object files without us having to list object files for non-builtin command implementations and it is not designed to be used by other people. +== 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. And when sending a patch in, do not forget to sign off your patches ;-) -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add documentation on how to integrate commands.
e...@thyrsus.com wrote on Sat, 24 Nov 2012 07:23 -0500: +== 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. Nice start. A few other details; I recently did this for git-p4 (python). .gitignore: ignore the auto-generated script, e.g. when git-foo.py is built into git-foo. INSTALL: note language requirements if odd (see python section) command-list.txt: categorization of commands for git(1) etc. RelNotes: Junio generally does this. Also please read Documentation/technical/api-builtin.txt to see how to add a built-in command. It also has comments that are identical for both built-in and stand-alone command. Could be that your text would better go near or with that one, as perhaps api-command.txt. -- Pete -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add documentation on how to integrate commands.
Pete Wyckoff p...@padd.com: Nice start. A few other details; I recently did this for git-p4 (python). .gitignore: ignore the auto-generated script, e.g. when git-foo.py is built into git-foo. INSTALL: note language requirements if odd (see python section) command-list.txt: categorization of commands for git(1) etc. RelNotes: Junio generally does this. Also please read Documentation/technical/api-builtin.txt to see how to add a built-in command. It also has comments that are identical for both built-in and stand-alone command. Could be that your text would better go near or with that one, as perhaps api-command.txt. Good points. I will submit a revised patch later today. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add documentation on how to integrate commands.
Working on my revised patch... Pete Wyckoff p...@padd.com: Nice start. A few other details; I recently did this for git-p4 (python). .gitignore: ignore the auto-generated script, e.g. when git-foo.py is built into git-foo. Added: 3. 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. INSTALL: note language requirements if odd (see python section) Added: 4. If your command has dependency on a particular version, document it in the INSTALL file. command-list.txt: categorization of commands for git(1) etc. Are the values in the right-hand column documented somewhere? What uses them, and for what purposes. RelNotes: Junio generally does this. Added: 6. When your patch is merged, remind the maintainer to add something about it in the RelNotes file. Also please read Documentation/technical/api-builtin.txt to see how to add a built-in command. It also has comments that are identical for both built-in and stand-alone command. Could be that your text would better go near or with that one, as perhaps api-command.txt. I think this is a good suggestion and will implement it. If someone can explain the values used in command-list.txt, or (better) point me to documentation of them, that will enable me to finish the revised patch. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Add documentation on how to integrate commands.
On 11/24/2012 01:23 PM, Eric S. Raymond wrote: --- 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 000..be248f7 --- /dev/null +++ b/Documentation/CommandIntegration @@ -0,0 +1,69 @@ [...] +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. I think that here a reference to the file t/README would help (and perhaps make part of your text redundant). Michael -- Michael Haggerty mhag...@alum.mit.edu http://softwareswirl.blogspot.com/ -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
