[PATCH 2/2] core-git documentation update

Reformat core-git.txt to asciidoc format.
Includes split-docs.pl to create individual txt, html and man pages.

<JC> Editorial note.  I've updated to add git-diff-cache -m and
git-update-cache --replace description on top of the version
David posted to the GIT list and got his OK.

Signed-off-by: David Greaves <david@dgreaves.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
David Greaves 2005-05-08 18:22:48 +01:00 committed by Junio C Hamano
parent aa575f815e
commit 03ea280249
3 changed files with 972 additions and 502 deletions

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,89 @@
The output format from "git-diff-cache", "git-diff-tree" and
"git-diff-files" is very similar.
These commands all compare two sets of things; what are
compared are different:
git-diff-cache <tree-ish>::
compares the <tree-ish> and the files on the filesystem.
git-diff-cache --cached <tree-ish>::
compares the <tree-ish> and the cache.
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
compares the trees named by the two arguments.
git-diff-files [<pattern>...]::
compares the cache and the files on the filesystem.
The following desription uses "old" and "new" to mean those
compared entities.
For files in old but not in new (i.e. removed):
-<mode> \t <type> \t <object> \t <path>
For files not in old but in new (i.e. added):
+<mode> \t <type> \t <object> \t <path>
For files that differ:
*<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>
<new-sha1> is shown as all 0's if new is a file on the
filesystem and it is out of sync with the cache. Example:
*100644->100644 blob 5be4a4.......->000000....... file.c
Generating patches with -p
--------------------------
When "git-diff-cache", "git-diff-tree", or "git-diff-files" are run
with a '-p' option, they do not produce the output described above
instead they produce a patch file.
The patch generation can be customized at two levels. This
customization also applies to "git-diff-tree-helper".
1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,
these commands internally invoke "diff" like this:
diff -L a/<path> -L a/<path> -pu <old> <new>
For added files, `/dev/null` is used for <old>. For removed
files, `/dev/null` is used for <new>
The "diff" formatting options can be customized via the
environment variable 'GIT_DIFF_OPTS'. For example, if you
prefer context diff:
GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)
2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
program named by it is called, instead of the diff invocation
described above.
+
For a path that is added, removed, or modified,
'GIT_EXTERNAL_DIFF' is called with 7 parameters:
path old-file old-hex old-mode new-file new-hex new-mode
+
where:
<old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
contents of <old|ne>,
<old|new>-hex:: are the 40-hexdigit SHA1 hashes,
<old|new>-mode:: are the octal representation of the file modes.
+
The file parameters can point at the user's working file
(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
when a new file is added), or a temporary file (e.g. `old-file` in the
cache). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
parameter, <path>.

44
Documentation/split_docs.pl Executable file
View File

@ -0,0 +1,44 @@
#!/usr/bin/perl -w
use strict;
my $cmd;
my $name;
my $author;
while (<STDIN>) {
if (/^NAME$/ || eof(STDIN)) {
if ($cmd) {
print PAGE $author if defined($author);
print PAGE "Documentation\n--------------\nDocumentation by David Greaves, Junio C Hamano and the git-list <git\@vger.kernel.org>.\n\n";
print PAGE "GIT\n---\nPart of the link:git.html[git] suite\n\n";
if ($#ARGV || $ARGV[0] eq "-html") {
system(qw(asciidoc -b css-embedded -d manpage), "$cmd.txt");
} elsif ($ARGV[0] eq "-man") {
system(qw(asciidoc -b docbook -d manpage), "$cmd.txt");
system(qw(xmlto man), "$cmd.xml") if -e "$cmd.xml";
}
}
exit if eof(STDIN);
$_=<STDIN>;$_=<STDIN>; # discard underline and get command
chomp;
$name = $_;
($cmd) = split(' ',$_);
print "$name\n";
open(PAGE, "> $cmd.txt") or die;
print PAGE "$cmd(1)\n==="."="x length($cmd);
print PAGE "\nv0.1, May 2005\n\nNAME\n----\n$name\n\n";
$author = "Author\n------\nWritten by Linus Torvalds <torvalds\@osdl.org>\n\n";
next;
}
next unless $cmd;
$author=undef if /^AUTHOR$/i; # don't use default for commands with an author
print PAGE $_;
}