@matheusbsbs / matheus-bagliano / commits / 530e741c72
Fork 0

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 there. 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 needed. Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Nov 24, 2007 at 23:48 UTC 530e741c726a612d78de21957d531dd2215483b4
27 files changed +675 -5
Documentation/.gitignore
+1
@@ -2,6 +2,7 @@
2 *.html
3 *.[1-8]
4 *.made
5 +git.info
6 howto-index.txt
7 doc.dep
8 cmds-*.txt
Documentation/Makefile
+15 -2
@@ -24,6 +24,9 @@ ARTICLES += git-tools
24 ARTICLES += glossary
25 # with their own formatting rules.
26 SP_ARTICLES = howto/revert-branch-rebase user-manual
27 +API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
28 +SP_ARTICLES += $(API_DOCS)
29 +SP_ARTICLES += technical/api-index
30
31 DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
32
@@ -142,10 +145,12 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
145 git.7 git.html: git.txt
146
147 clean:
145 - $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep
148 + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ git.info
149 + $(RM) howto-index.txt howto/*.html doc.dep
150 + $(RM) technical/api-*.html technical/api-index.txt
151 $(RM) $(cmds_txt) *.made
152
148 -%.html : %.txt
153 +$(MAN_HTML): %.html : %.txt
154 $(RM) $@+ $@
155 $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
156 $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $<
@@ -164,6 +169,14 @@ clean:
169 user-manual.xml: user-manual.txt user-manual.conf
170 $(ASCIIDOC) -b docbook -d book $<
171
172 +technical/api-index.txt: technical/api-index-skel.txt \
173 + technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
174 + cd technical && sh ./api-index.sh
175 +
176 +$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
177 + $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
178 + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
179 +
180 XSLT = docbook.xsl
181 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
182
Documentation/git.txt
+2
@@ -153,6 +153,8 @@ introductions to the underlying git architecture.
153 See also the link:howto-index.html[howto] documents for some useful
154 examples.
155
156 +The internals are documented link:technical/api-index.html[here].
157 +
158 GIT COMMANDS
159 ------------
160
Documentation/install-webdoc.sh
+13 -3
@@ -2,9 +2,16 @@
2
3 T="$1"
4
5 -for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css
5 +for h in \
6 + *.txt *.html \
7 + howto/*.txt howto/*.html \
8 + technical/*.txt technical/*.html \
9 + RelNotes-*.txt *.css
10 do
7 - if test -f "$T/$h" &&
11 + if test ! -f "$h"
12 + then
13 + : did not match
14 + elif test -f "$T/$h" &&
15 diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
16 then
17 :; # up to date
@@ -16,7 +23,10 @@ do
23 fi
24 done
25 strip_leading=`echo "$T/" | sed -e 's|.|.|g'`
19 -for th in "$T"/*.html "$T"/*.txt "$T"/howto/*.txt "$T"/howto/*.html
26 +for th in \
27 + "$T"/*.html "$T"/*.txt \
28 + "$T"/howto/*.txt "$T"/howto/*.html \
29 + "$T"/technical/*.txt "$T"/technical/*.html
30 do
31 h=`expr "$th" : "$strip_leading"'\(.*\)'`
32 case "$h" in
Documentation/technical/.gitignore new
+1
@@ -0,0 +1 @@
1 +api-index.txt
Documentation/technical/api-allocation-growing.txt new
+34
@@ -0,0 +1,34 @@
1 +allocation growing API
2 +======================
3 +
4 +Dynamically growing an array using realloc() is error prone and boring.
5 +
6 +Define your array with:
7 +
8 +* a pointer (`ary`) that points at the array, initialized to `NULL`;
9 +
10 +* an integer variable (`alloc`) that keeps track of how big the current
11 + allocation is, initialized to `0`;
12 +
13 +* another integer variable (`nr`) to keep track of how many elements the
14 + array currently has, initialized to `0`.
15 +
16 +Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
17 +alloc)`. This ensures that the array can hold at least `n` elements by
18 +calling `realloc(3)` and adjusting `alloc` variable.
19 +
20 +------------
21 +sometype *ary;
22 +size_t nr;
23 +size_t alloc
24 +
25 +for (i = 0; i < nr; i++)
26 + if (we like ary[i] already)
27 + return;
28 +
29 +/* we did not like any existing one, so add one */
30 +ALLOC_GROW(ary, nr + 1, alloc);
31 +ary[nr++] = value you like;
32 +------------
33 +
34 +You are responsible for updating the `nr` variable.
Documentation/technical/api-builtin.txt new
+63
@@ -0,0 +1,63 @@
1 +builtin API
2 +===========
3 +
4 +Adding a new built-in
5 +---------------------
6 +
7 +There are 4 things to do to add a bulit-in command implementation to
8 +git:
9 +
10 +. Define the implementation of the built-in command `foo` with
11 + signature:
12 +
13 + int cmd_foo(int argc, const char **argv, const char *prefix);
14 +
15 +. Add the external declaration for the function to `builtin.h`.
16 +
17 +. Add the command to `commands[]` table in `handle_internal_command()`,
18 + defined in `git.c`. The entry should look like:
19 +
20 + { "foo", cmd_foo, <options> },
21 +
22 + where options is the bitwise-or of:
23 +
24 +`RUN_SETUP`::
25 +
26 + Make sure there is a git directory to work on, and if there is a
27 + work tree, chdir to the top of it if the command was invoked
28 + in a subdirectory. If there is no work tree, no chdir() is
29 + done.
30 +
31 +`USE_PAGER`::
32 +
33 + If the standard output is connected to a tty, spawn a pager and
34 + feed our output to it.
35 +
36 +. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
37 +
38 +Additionally, if `foo` is a new command, there are 3 more things to do:
39 +
40 +. Add tests to `t/` directory.
41 +
42 +. Write documentation in `Documentation/git-foo.txt`.
43 +
44 +. Add an entry for `git-foo` to the list at the end of
45 + `Documentation/cmd-list.perl`.
46 +
47 +
48 +How a built-in is called
49 +------------------------
50 +
51 +The implementation `cmd_foo()` takes three parameters, `argc`, `argv,
52 +and `prefix`. The first two are similar to what `main()` of a
53 +standalone command would be called with.
54 +
55 +When `RUN_SETUP` is specified in the `commands[]` table, and when you
56 +were started from a subdirectory of the work tree, `cmd_foo()` is called
57 +after chdir(2) to the top of the work tree, and `prefix` gets the path
58 +to the subdirectory the command started from. This allows you to
59 +convert a user-supplied pathname (typically relative to that directory)
60 +to a pathname relative to the top of the work tree.
61 +
62 +The return value from `cmd_foo()` becomes the exit status of the
63 +command.
Documentation/technical/api-decorate.txt new
+6
@@ -0,0 +1,6 @@
1 +decorate API
2 +============
3 +
4 +Talk about <decorate.h>
5 +
6 +(Linus)
Documentation/technical/api-diff.txt new
+166
@@ -0,0 +1,166 @@
1 +diff API
2 +========
3 +
4 +The diff API is for programs that compare two sets of files (e.g. two
5 +trees, one tree and the index) and present the found difference in
6 +various ways. The calling program is responsible for feeding the API
7 +pairs of files, one from the "old" set and the corresponding one from
8 +"new" set, that are different. The library called through this API is
9 +called diffcore, and is responsible for two things.
10 +
11 +* finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and
12 + changes that touch a string (`-S`), as specified by the caller.
13 +
14 +* outputting the differences in various formats, as specified by the
15 + caller.
16 +
17 +Calling sequence
18 +----------------
19 +
20 +* Prepare `struct diff_options` to record the set of diff options, and
21 + then call `diff_setup()` to initialize this structure. This sets up
22 + the vanilla default.
23 +
24 +* Fill in the options structure to specify desired output format, rename
25 + detection, etc. `diff_opt_parse()` can be used to parse options given
26 + from the command line in a way consistent with existing git-diff
27 + family of programs.
28 +
29 +* Call `diff_setup_done()`; this inspects the options set up so far for
30 + internal consistency and make necessary tweaking to it (e.g. if
31 + textual patch output was asked, recursive behaviour is turned on).
32 +
33 +* As you find different pairs of files, call `diff_change()` to feed
34 + modified files, `diff_addremove()` to feed created or deleted files,
35 + or `diff_unmerged()` to feed a file whose state is 'unmerged' to the
36 + API. These are thin wrappers to a lower-level `diff_queue()` function
37 + that is flexible enough to record any of these kinds of changes.
38 +
39 +* Once you finish feeding the pairs of files, call `diffcore_std()`.
40 + This will tell the diffcore library to go ahead and do its work.
41 +
42 +* Calling `diffcore_flush()` will produce the output.
43 +
44 +
45 +Data structures
46 +---------------
47 +
48 +* `struct diff_filespec`
49 +
50 +This is the internal representation for a single file (blob). It
51 +records the blob object name (if known -- for a work tree file it
52 +typically is a NUL SHA-1), filemode and pathname. This is what the
53 +`diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and
54 +feed `diff_queue()` function with.
55 +
56 +* `struct diff_filepair`
57 +
58 +This records a pair of `struct diff_filespec`; the filespec for a file
59 +in the "old" set (i.e. preimage) is called `one`, and the filespec for a
60 +file in the "new" set (i.e. postimage) is called `two`. A change that
61 +represents file creation has NULL in `one`, and file deletion has NULL
62 +in `two`.
63 +
64 +A `filepair` starts pointing at `one` and `two` that are from the same
65 +filename, but `diffcore_std()` can break pairs and match component
66 +filespecs with other filespecs from a different filepair to form new
67 +filepair. This is called 'rename detection'.
68 +
69 +* `struct diff_queue`
70 +
71 +This is a collection of filepairs. Notable members are:
72 +
73 +`queue`::
74 +
75 + An array of pointers to `struct diff_filepair`. This
76 + dynamically grows as you add filepairs;
77 +
78 +`alloc`::
79 +
80 + The allocated size of the `queue` array;
81 +
82 +`nr`::
83 +
84 + The number of elements in the `queue` array.
85 +
86 +
87 +* `struct diff_options`
88 +
89 +This describes the set of options the calling program wants to affect
90 +the operation of diffcore library with.
91 +
92 +Notable members are:
93 +
94 +`output_format`::
95 + The output format used when `diff_flush()` is run.
96 +
97 +`context`::
98 + Number of context lines to generate in patch output.
99 +
100 +`break_opt`, `detect_rename`, `rename-score`, `rename_limit`::
101 + Affects the way detection logic for complete rewrites, renames
102 + and copies.
103 +
104 +`abbrev`::
105 + Number of hexdigits to abbrevate raw format output to.
106 +
107 +`pickaxe`::
108 + A constant string (can and typically does contain newlines to
109 + look for a block of text, not just a single line) to filter out
110 + the filepairs that do not change the number of strings contained
111 + in its preimage and postmage of the diff_queue.
112 +
113 +`flags`::
114 + This is mostly a collection of boolean options that affects the
115 + operation, but some do not have anything to do with the diffcore
116 + library.
117 +
118 +BINARY, TEXT;;
119 + Affects the way how a file that is seemingly binary is treated.
120 +
121 +FULL_INDEX;;
122 + Tells the patch output format not to use abbreviated object
123 + names on the "index" lines.
124 +
125 +FIND_COPIES_HARDER;;
126 + Tells the diffcore library that the caller is feeding unchanged
127 + filepairs to allow copies from unmodified files be detected.
128 +
129 +COLOR_DIFF;;
130 + Output should be colored.
131 +
132 +COLOR_DIFF_WORDS;;
133 + Output is a colored word-diff.
134 +
135 +NO_INDEX;;
136 + Tells diff-files that the input is not tracked files but files
137 + in random locations on the filesystem.
138 +
139 +ALLOW_EXTERNAL;;
140 + Tells output routine that it is Ok to call user specified patch
141 + output routine. Plumbing disables this to ensure stable output.
142 +
143 +QUIET;;
144 + Do not show any output.
145 +
146 +REVERSE_DIFF;;
147 + Tells the library that the calling program is feeding the
148 + filepairs reversed; `one` is two, and `two` is one.
149 +
150 +EXIT_WITH_STATUS;;
151 + For communication between the calling program and the options
152 + parser; tell the calling program to signal the presense of
153 + difference using program exit code.
154 +
155 +HAS_CHANGES;;
156 + Internal; used for optimization to see if there is any change.
157 +
158 +SILENT_ON_REMOVE;;
159 + Affects if diff-files shows removed files.
160 +
161 +RECURSIVE, TREE_IN_RECURSIVE;;
162 + Tells if tree traversal done by tree-diff should recursively
163 + descend into a tree object pair that are different in preimage
164 + and postimage set.
165 +
166 +(JC)
Documentation/technical/api-directory-listing.txt new
+76
@@ -0,0 +1,76 @@
1 +directory listing API
2 +=====================
3 +
4 +The directory listing API is used to enumerate paths in the work tree,
5 +optionally taking `.git/info/exclude` and `.gitignore` files per
6 +directory into account.
7 +
8 +Data structure
9 +--------------
10 +
11 +`struct dir_struct` structure is used to pass directory traversal
12 +options to the library and to record the paths discovered. The notable
13 +options are:
14 +
15 +`exclude_per_dir`::
16 +
17 + The name of the file to be read in each directory for excluded
18 + files (typically `.gitignore`).
19 +
20 +`collect_ignored`::
21 +
22 + Include paths that are to be excluded in the result.
23 +
24 +`show_ignored`::
25 +
26 + The traversal is for finding just ignored files, not unignored
27 + files.
28 +
29 +`show_other_directories`::
30 +
31 + Include a directory that is not tracked.
32 +
33 +`hide_empty_directories`::
34 +
35 + Do not include a directory that is not tracked and is empty.
36 +
37 +`no_gitlinks`::
38 +
39 + If set, recurse into a directory that looks like a git
40 + directory. Otherwise it is shown as a directory.
41 +
42 +The result of the enumeration is left in these fields::
43 +
44 +`entries[]`::
45 +
46 + An array of `struct dir_entry`, each element of which describes
47 + a path.
48 +
49 +`nr`::
50 +
51 + The number of members in `entries[]` array.
52 +
53 +`alloc`::
54 +
55 + Internal use; keeps track of allocation of `entries[]` array.
56 +
57 +
58 +Calling sequence
59 +----------------
60 +
61 +* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
62 + sizeof(dir))`.
63 +
64 +* Call `add_exclude()` to add single exclude pattern,
65 + `add_excludes_from_file()` to add patterns from a file
66 + (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A
67 + short-hand function `setup_standard_excludes()` can be used to set up
68 + the standard set of exclude settings.
69 +
70 +* Set options described in the Data Structure section above.
71 +
72 +* Call `read_directory()`.
73 +
74 +* Use `dir.entries[]`.
75 +
76 +(JC)
Documentation/technical/api-gitattributes.txt new
+111
@@ -0,0 +1,111 @@
1 +gitattributes API
2 +=================
3 +
4 +gitattributes mechanism gives a uniform way to associate various
5 +attributes to set of paths.
6 +
7 +
8 +Data Structure
9 +--------------
10 +
11 +`struct git_attr`::
12 +
13 + An attribute is an opaque object that is identified by its name.
14 + Pass the name and its length to `git_attr()` function to obtain
15 + the object of this type. The internal representation of this
16 + structure is of no interest to the calling programs.
17 +
18 +`struct git_attr_check`::
19 +
20 + This structure represents a set of attributes to check in a call
21 + to `git_checkattr()` function, and receives the results.
22 +
23 +
24 +Calling Sequence
25 +----------------
26 +
27 +* Prepare an array of `struct git_attr_check` to define the list of
28 + attributes you would want to check. To populate this array, you would
29 + need to define necessary attributes by calling `git_attr()` function.
30 +
31 +* Call git_checkattr() to check the attributes for the path.
32 +
33 +* Inspect `git_attr_check` structure to see how each of the attribute in
34 + the array is defined for the path.
35 +
36 +
37 +Attribute Values
38 +----------------
39 +
40 +An attribute for a path can be in one of four states: Set, Unset,
41 +Unspecified or set to a string, and `.value` member of `struct
42 +git_attr_check` records it. There are three macros to check these:
43 +
44 +`ATTR_TRUE()`::
45 +
46 + Returns true if the attribute is Set for the path.
47 +
48 +`ATTR_FALSE()`::
49 +
50 + Returns true if the attribute is Unset for the path.
51 +
52 +`ATTR_UNSET()`::
53 +
54 + Returns true if the attribute is Unspecified for the path.
55 +
56 +If none of the above returns true, `.value` member points at a string
57 +value of the attribute for the path.
58 +
59 +
60 +Example
61 +-------
62 +
63 +To see how attributes "crlf" and "indent" are set for different paths.
64 +
65 +. Prepare an array of `struct git_attr_check` with two elements (because
66 + we are checking two attributes). Initialize their `attr` member with
67 + pointers to `struct git_attr` obtained by calling `git_attr()`:
68 +
69 +------------
70 +static struct git_attr_check check[2];
71 +static void setup_check(void)
72 +{
73 + if (check[0].attr)
74 + return; /* already done */
75 + check[0].attr = git_attr("crlf", 4);
76 + check[1].attr = git_attr("ident", 5);
77 +}
78 +------------
79 +
80 +. Call `git_checkattr()` with the prepared array of `struct git_attr_check`:
81 +
82 +------------
83 + const char *path;
84 +
85 + setup_check();
86 + git_checkattr(path, ARRAY_SIZE(check), check);
87 +------------
88 +
89 +. Act on `.value` member of the result, left in `check[]`:
90 +
91 +------------
92 + const char *value = check[0].value;
93 +
94 + if (ATTR_TRUE(value)) {
95 + The attribute is Set, by listing only the name of the
96 + attribute in the gitattributes file for the path.
97 + } else if (ATTR_FALSE(value)) {
98 + The attribute is Unset, by listing the name of the
99 + attribute prefixed with a dash - for the path.
100 + } else if (ATTR_UNSET(value)) {
101 + The attribute is not set nor unset for the path.
102 + } else if (!strcmp(value, "input")) {
103 + If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is
104 + true, the value is a string set in the gitattributes
105 + file for the path by saying "attr=value".
106 + } else if (... other check using value as string ...) {
107 + ...
108 + }
109 +------------
110 +
111 +(JC)
Documentation/technical/api-grep.txt new
+8
@@ -0,0 +1,8 @@
1 +grep API
2 +========
3 +
4 +Talk about <grep.h>, things like:
5 +
6 +* grep_buffer()
7 +
8 +(JC)
Documentation/technical/api-hash.txt new
+6
@@ -0,0 +1,6 @@
1 +hash API
2 +========
3 +
4 +Talk about <hash.h>
5 +
6 +(Linus)
Documentation/technical/api-in-core-index.txt new
+21
@@ -0,0 +1,21 @@
1 +in-core index API
2 +=================
3 +
4 +Talk about <read-cache.c> and <cache-tree.c>, things like:
5 +
6 +* cache -> the_index macros
7 +* read_index()
8 +* write_index()
9 +* ie_match_stat() and ie_modified(); how they are different and when to
10 + use which.
11 +* index_name_pos()
12 +* remove_index_entry_at()
13 +* remove_file_from_index()
14 +* add_file_to_index()
15 +* add_index_entry()
16 +* refresh_index()
17 +* discard_index()
18 +* cache_tree_invalidate_path()
19 +* cache_tree_update()
20 +
21 +(JC, Linus)
Documentation/technical/api-index-skel.txt new
+15
@@ -0,0 +1,15 @@
1 +GIT API Documents
2 +=================
3 +
4 +GIT has grown a set of internal API over time. This collection
5 +documents them.
6 +
7 +////////////////////////////////////////////////////////////////
8 +// table of contents begin
9 +////////////////////////////////////////////////////////////////
10 +
11 +////////////////////////////////////////////////////////////////
12 +// table of contents end
13 +////////////////////////////////////////////////////////////////
14 +
15 +2007-11-24
Documentation/technical/api-index.sh new
+28
@@ -0,0 +1,28 @@
1 +#!/bin/sh
2 +
3 +(
4 + c=////////////////////////////////////////////////////////////////
5 + skel=api-index-skel.txt
6 + sed -e '/^\/\/ table of contents begin/q' "$skel"
7 + echo "$c"
8 +
9 + ls api-*.txt |
10 + while read filename
11 + do
12 + case "$filename" in
13 + api-index-skel.txt | api-index.txt) continue ;;
14 + esac
15 + title=$(sed -e 1q "$filename")
16 + html=${filename%.txt}.html
17 + echo "* link:$html[$title]"
18 + done
19 + echo "$c"
20 + sed -n -e '/^\/\/ table of contents end/,$p' "$skel"
21 +) >api-index.txt+
22 +
23 +if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null
24 +then
25 + rm -f api-index.txt+
26 +else
27 + mv api-index.txt+ api-index.txt
28 +fi
Documentation/technical/api-lockfile.txt new
+12
@@ -0,0 +1,12 @@
1 +lockfile API
2 +============
3 +
4 +Talk about <lockfile.c>, things like:
5 +
6 +* lockfile lifetime -- atexit(3) looks at them, do not put them on the
7 + stack;
8 +* hold_lock_file_for_update()
9 +* commit_lock_file()
10 +* rollback_rock_file()
11 +
12 +(JC, Dscho, Shawn)
Documentation/technical/api-object-access.txt new
+15
@@ -0,0 +1,15 @@
1 +object access API
2 +=================
3 +
4 +Talk about <sha1_file.c> and <object.h> family, things like
5 +
6 +* read_sha1_file()
7 +* read_object_with_reference()
8 +* has_sha1_file()
9 +* write_sha1_file()
10 +* pretend_sha1_file()
11 +* lookup_{object,commit,tag,blob,tree}
12 +* parse_{object,commit,tag,blob,tree}
13 +* Use of object flags
14 +
15 +(JC, Shawn, Daniel, Dscho, Linus)
Documentation/technical/api-parse-options.txt new
+6
@@ -0,0 +1,6 @@
1 +parse-options API
2 +=================
3 +
4 +Talk about <parse-options.h>
5 +
6 +(Pierre)
Documentation/technical/api-path-list.txt new
+9
@@ -0,0 +1,9 @@
1 +path-list API
2 +=============
3 +
4 +Talk about <path-list.h>, things like
5 +
6 +* it is not just paths but strings in general;
7 +* the calling sequence.
8 +
9 +(Dscho)
Documentation/technical/api-quote.txt new
+10
@@ -0,0 +1,10 @@
1 +quote API
2 +=========
3 +
4 +Talk about <quote.h>, things like
5 +
6 +* sq_quote and unquote
7 +* c_style quote and unquote
8 +* quoting for foreign languages
9 +
10 +(JC)
Documentation/technical/api-revision-walking.txt new
+9
@@ -0,0 +1,9 @@
1 +revision walking API
2 +====================
3 +
4 +Talk about <revision.h>, things like:
5 +
6 +* two diff_options, one for path limiting, another for output;
7 +* calling sequence: init_revisions(), setup_revsions(), get_revision();
8 +
9 +(Linus, JC, Dscho)
Documentation/technical/api-run-command.txt new
+10
@@ -0,0 +1,10 @@
1 +run-command API
2 +===============
3 +
4 +Talk about <run-command.h>, and things like:
5 +
6 +* Environment the command runs with (e.g. GIT_DIR);
7 +* File descriptors and pipes;
8 +* Exit status;
9 +
10 +(Hannes, Dscho, Shawn)
Documentation/technical/api-setup.txt new
+13
@@ -0,0 +1,13 @@
1 +setup API
2 +=========
3 +
4 +Talk about
5 +
6 +* setup_git_directory()
7 +* setup_git_directory_gently()
8 +* is_inside_git_dir()
9 +* is_inside_work_tree()
10 +* setup_work_tree()
11 +* get_pathspec()
12 +
13 +(Dscho)
Documentation/technical/api-strbuf.txt new
+6
@@ -0,0 +1,6 @@
1 +strbuf API
2 +==========
3 +
4 +Talk about <strbuf.h>
5 +
6 +(Pierre, JC)
Documentation/technical/api-tree-walking.txt new
+12
@@ -0,0 +1,12 @@
1 +tree walking API
2 +================
3 +
4 +Talk about <tree-walk.h>, things like
5 +
6 +* struct tree_desc
7 +* init_tree_desc
8 +* tree_entry_extract
9 +* update_tree_entry
10 +* get_tree_entry
11 +
12 +(JC, Linus)
Documentation/technical/api-xdiff-interface.txt new
+7
@@ -0,0 +1,7 @@
1 +xdiff interface API
2 +===================
3 +
4 +Talk about our calling convention to xdiff library, including
5 +xdiff_emit_consume_fn.
6 +
7 +(Dscho, JC)