Hi
I'm starting to write some docs... Comments... even "yep, looks OK, carry on" :)
I plan on putting the 'git command' ones into the 'git help ...' structure once Petr accepts it.
I guess the low level ones go into a README.reference until they stabilise and become man pages...
In doing this I noticed a couple of points: * update-cache won't accept ./file or fred/./file * checkout-cache doesn't seem to preserve mode
Are these bugs or should they be documented? I've taken the approach of documenting behaviour for now.
Signed-off-by: David Greaves <[EMAIL PROTECTED]> ---
Index: README.reference =================================================================== --- /dev/null (tree:cf6a46a2199777c3dac32fa4479b97c0752cdf07) +++ 30de093673d44c7ea8c56a0194fb792e47225ac8/README.reference (mode:100644 sha1:2ec6683b22e5672ea46d27770fcb1a4b4c37aa0e) @@ -0,0 +1,158 @@ +Terminology: - see README for description +Each line contains terms used interchangeably + +object database, .git directory +directory cache, index +id, sha1, sha1-id, sha1 hash +type, tag, tagname +blob, blob object +tree, tree object +commit, commit object +parent +root object +changeset + +################################################################ +cat-file + cat-file <-t | tagname> <sha1> + +Provide contents or type of objects in the repository. The tagname is +required if it is not being interrogated. + + +<sha1> + The sha1 identifier of the object. + (This is the sha1 of the uncompressed content.) + +-t + show the object type identified by <sha1> + One of: blob/tree/commit + +<tagname> + One of: blob/tree/commit + + +################################################################ +check-files + check-files <file>... + +Check that a list of files are up-to-date between the filesystem and +the cache. Used to verify a patch target before doing a patch. + +Files that do not exist on the filesystem are considered up-to-date +(whether or not they are in the cache). + +Emits an error message on failure. + +exits with a status code indicating success if all files are +up-to-date. + + +see also: update-cache + + +################################################################ +checkout-cache + checkout-cache [-q] [-a] [-f] [--] <file>... + +Will copy all files listed from the cache to the working directory +(not overwriting existing files). Note that the file contents are +restored - NOT the file permissions. + +-q + be quiet if files exist or are not in the cache + +-f + forces overwrite of existing files + +-a + checks out all files in the cache before processing listed + files. + +Note that the order of the flags matters: + + checkout-cache -a -f file.c + +will first check out all files listed in the cache (but not overwrite +any old ones), and then force-checkout file.c a second time (ie that +one _will_ overwrite any old contents with the same filename). + +Also, just doing "checkout-cache" does nothing. You probably meant +"checkout-cache -a". And if you want to force it, you want +"checkout-cache -f -a". + +Intuitiveness is not the goal here. Repeatability is. The reason for +the "no arguments means no work" thing is that from scripts you are +supposed to be able to do things like + + find . -name '*.h' -print0 | xargs -0 checkout-cache -f -- + +which will force all existing *.h files to be replaced with their +cached copies. If an empty command line implied "all", then this would +force-refresh everything in the cache, which was not the point. + +Oh, and the "--" is just a good idea when you know the rest will be +filenames. Just so that you wouldn't have a filename of "-a" causing +problems (not possible in the above example, but get used to it in +scripting!). + + +################################################################ +commit-id + commit-id [tag] + +Returns the sha1-id of the commit object associated with given tag. + +tag + tag of commit object - defaults to the current HEAD. + + +################################################################ +commit-tree + commit-tree <sha1> [-p <sha1>]* < changelog + + +################################################################ +diff-tree + diff-tree [-r] [-z] <tree sha1> <tree sha1> + + +################################################################ +ls-tree + ls-tree [-r] [-z] <key> + + +################################################################ +merge-base + merge-base <commit-id> <commit-id> + + +################################################################ +merge-cache + merge-cache <merge-program> (-a | <filename>*) + + +################################################################ +read-tree + read-tree [-m] <sha1> + + +################################################################ +rev-tree + rev-tree [--edges] [--cache <cache-file>] <commit-id> [<commit-id>] + + +################################################################ +show-diff + show-diff [-q] [-s] [-z] [paths...] + + +################################################################ +show-files + show-files [-z] [-t] (--[cached|deleted|others|ignored|stage])* + + +################################################################ +unpack-file + unpack-file.c <sha1> +
