Browse files

Start preparing the API documents.

Most of them are still stubs, but the procedure to build the HTML
documentation, maintaining the index and installing the end product are

I placed names of people who are likely to know the most about the topic
in the stub files, so that volunteers will know whom to ask questions as

Signed-off-by: Junio C Hamano <>
  • Loading branch information...
1 parent fa47016 commit 530e741c726a612d78de21957d531dd2215483b4 @gitster gitster committed Nov 25, 2007
@@ -2,6 +2,7 @@
@@ -24,6 +24,9 @@ ARTICLES += git-tools
ARTICLES += glossary
# with their own formatting rules.
SP_ARTICLES = howto/revert-branch-rebase user-manual
+API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
+SP_ARTICLES += technical/api-index
DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
@@ -142,10 +145,12 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
git.7 git.html: git.txt
- $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep
+ $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+
+ $(RM) howto-index.txt howto/*.html doc.dep
+ $(RM) technical/api-*.html technical/api-index.txt
$(RM) $(cmds_txt) *.made
-%.html : %.txt
+$(MAN_HTML): %.html : %.txt
$(RM) $@+ $@
$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $<
@@ -164,6 +169,14 @@ clean:
user-manual.xml: user-manual.txt user-manual.conf
$(ASCIIDOC) -b docbook -d book $<
+technical/api-index.txt: technical/api-index-skel.txt \
+ technical/ $(patsubst %,%.txt,$(API_DOCS))
+ cd technical && sh ./
+$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
+ $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
+ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
XSLT = docbook.xsl
XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
@@ -153,6 +153,8 @@ introductions to the underlying git architecture.
See also the link:howto-index.html[howto] documents for some useful
+The internals are documented link:technical/api-index.html[here].
@@ -2,9 +2,16 @@
-for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css
+for h in \
+ *.txt *.html \
+ howto/*.txt howto/*.html \
+ technical/*.txt technical/*.html \
+ RelNotes-*.txt *.css
- if test -f "$T/$h" &&
+ if test ! -f "$h"
+ then
+ : did not match
+ elif test -f "$T/$h" &&
diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
:; # up to date
@@ -16,7 +23,10 @@ do
strip_leading=`echo "$T/" | sed -e 's|.|.|g'`
-for th in "$T"/*.html "$T"/*.txt "$T"/howto/*.txt "$T"/howto/*.html
+for th in \
+ "$T"/*.html "$T"/*.txt \
+ "$T"/howto/*.txt "$T"/howto/*.html \
+ "$T"/technical/*.txt "$T"/technical/*.html
h=`expr "$th" : "$strip_leading"'\(.*\)'`
case "$h" in
@@ -0,0 +1 @@
@@ -0,0 +1,34 @@
+allocation growing API
+Dynamically growing an array using realloc() is error prone and boring.
+Define your array with:
+* a pointer (`ary`) that points at the array, initialized to `NULL`;
+* an integer variable (`alloc`) that keeps track of how big the current
+ allocation is, initialized to `0`;
+* another integer variable (`nr`) to keep track of how many elements the
+ array currently has, initialized to `0`.
+Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
+alloc)`. This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+sometype *ary;
+size_t nr;
+size_t alloc
+for (i = 0; i < nr; i++)
+ if (we like ary[i] already)
+ return;
+/* we did not like any existing one, so add one */
+ALLOC_GROW(ary, nr + 1, alloc);
+ary[nr++] = value you like;
+You are responsible for updating the `nr` variable.
@@ -0,0 +1,63 @@
+builtin API
+Adding a new built-in
+There are 4 things to do to add a bulit-in command implementation to
+. Define the implementation of the built-in command `foo` with
+ signature:
+ int cmd_foo(int argc, const char **argv, const char *prefix);
+. Add the external declaration for the function to `builtin.h`.
+. Add the command to `commands[]` table in `handle_internal_command()`,
+ defined in `git.c`. The entry should look like:
+ { "foo", cmd_foo, <options> },
+ where options is the bitwise-or of:
+ Make sure there is a git directory to work on, and if there is a
+ work tree, chdir to the top of it if the command was invoked
+ in a subdirectory. If there is no work tree, no chdir() is
+ done.
+ If the standard output is connected to a tty, spawn a pager and
+ feed our output to it.
+. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
+Additionally, if `foo` is a new command, there are 3 more things to do:
+. Add tests to `t/` directory.
+. Write documentation in `Documentation/git-foo.txt`.
+. Add an entry for `git-foo` to the list at the end of
+ `Documentation/cmd-list.perl`.
+How a built-in is called
+The implementation `cmd_foo()` takes three parameters, `argc`, `argv,
+and `prefix`. The first two are similar to what `main()` of a
+standalone command would be called with.
+When `RUN_SETUP` is specified in the `commands[]` table, and when you
+were started from a subdirectory of the work tree, `cmd_foo()` is called
+after chdir(2) to the top of the work tree, and `prefix` gets the path
+to the subdirectory the command started from. This allows you to
+convert a user-supplied pathname (typically relative to that directory)
+to a pathname relative to the top of the work tree.
+The return value from `cmd_foo()` becomes the exit status of the
@@ -0,0 +1,6 @@
+decorate API
+Talk about <decorate.h>
@@ -0,0 +1,166 @@
+diff API
+The diff API is for programs that compare two sets of files (e.g. two
+trees, one tree and the index) and present the found difference in
+various ways. The calling program is responsible for feeding the API
+pairs of files, one from the "old" set and the corresponding one from
+"new" set, that are different. The library called through this API is
+called diffcore, and is responsible for two things.
+* finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and
+ changes that touch a string (`-S`), as specified by the caller.
+* outputting the differences in various formats, as specified by the
+ caller.
+Calling sequence
+* Prepare `struct diff_options` to record the set of diff options, and
+ then call `diff_setup()` to initialize this structure. This sets up
+ the vanilla default.
+* Fill in the options structure to specify desired output format, rename
+ detection, etc. `diff_opt_parse()` can be used to parse options given
+ from the command line in a way consistent with existing git-diff
+ family of programs.
+* Call `diff_setup_done()`; this inspects the options set up so far for
+ internal consistency and make necessary tweaking to it (e.g. if
+ textual patch output was asked, recursive behaviour is turned on).
+* As you find different pairs of files, call `diff_change()` to feed
+ modified files, `diff_addremove()` to feed created or deleted files,
+ or `diff_unmerged()` to feed a file whose state is 'unmerged' to the
+ API. These are thin wrappers to a lower-level `diff_queue()` function
+ that is flexible enough to record any of these kinds of changes.
+* Once you finish feeding the pairs of files, call `diffcore_std()`.
+ This will tell the diffcore library to go ahead and do its work.
+* Calling `diffcore_flush()` will produce the output.
+Data structures
+* `struct diff_filespec`
+This is the internal representation for a single file (blob). It
+records the blob object name (if known -- for a work tree file it
+typically is a NUL SHA-1), filemode and pathname. This is what the
+`diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and
+feed `diff_queue()` function with.
+* `struct diff_filepair`
+This records a pair of `struct diff_filespec`; the filespec for a file
+in the "old" set (i.e. preimage) is called `one`, and the filespec for a
+file in the "new" set (i.e. postimage) is called `two`. A change that
+represents file creation has NULL in `one`, and file deletion has NULL
+in `two`.
+A `filepair` starts pointing at `one` and `two` that are from the same
+filename, but `diffcore_std()` can break pairs and match component
+filespecs with other filespecs from a different filepair to form new
+filepair. This is called 'rename detection'.
+* `struct diff_queue`
+This is a collection of filepairs. Notable members are:
+ An array of pointers to `struct diff_filepair`. This
+ dynamically grows as you add filepairs;
+ The allocated size of the `queue` array;
+ The number of elements in the `queue` array.
+* `struct diff_options`
+This describes the set of options the calling program wants to affect
+the operation of diffcore library with.
+Notable members are:
+ The output format used when `diff_flush()` is run.
+ Number of context lines to generate in patch output.
+`break_opt`, `detect_rename`, `rename-score`, `rename_limit`::
+ Affects the way detection logic for complete rewrites, renames
+ and copies.
+ Number of hexdigits to abbrevate raw format output to.
+ A constant string (can and typically does contain newlines to
+ look for a block of text, not just a single line) to filter out
+ the filepairs that do not change the number of strings contained
+ in its preimage and postmage of the diff_queue.
+ This is mostly a collection of boolean options that affects the
+ operation, but some do not have anything to do with the diffcore
+ library.
+ Affects the way how a file that is seemingly binary is treated.
+ Tells the patch output format not to use abbreviated object
+ names on the "index" lines.
+ Tells the diffcore library that the caller is feeding unchanged
+ filepairs to allow copies from unmodified files be detected.
+ Output should be colored.
+ Output is a colored word-diff.
+ Tells diff-files that the input is not tracked files but files
+ in random locations on the filesystem.
+ Tells output routine that it is Ok to call user specified patch
+ output routine. Plumbing disables this to ensure stable output.
+ Do not show any output.
+ Tells the library that the calling program is feeding the
+ filepairs reversed; `one` is two, and `two` is one.
+ For communication between the calling program and the options
+ parser; tell the calling program to signal the presense of
+ difference using program exit code.
+ Internal; used for optimization to see if there is any change.
+ Affects if diff-files shows removed files.
+ Tells if tree traversal done by tree-diff should recursively
+ descend into a tree object pair that are different in preimage
+ and postimage set.
Oops, something went wrong.

0 comments on commit 530e741

Please sign in to comment.