[PATCH] Some documentation...

[David Greaves <david@dgreaves.com>]

[-- Attachment #1: Type: text/plain, Size: 587 bytes --]

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 <david@dgreaves.com>
---



[-- Attachment #2: README.reference.patch --]
[-- Type: text/x-patch, Size: 4597 bytes --]

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>
+