[PATCH] Some documentation...

[PATCH] Some documentation...

[David Greaves]

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

Re: [PATCH] Some documentation...

[C. Scott Ananian]

On Wed, 20 Apr 2005, David Greaves wrote:

> In doing this I noticed a couple of points:
> * update-cache won't accept ./file or fred/./file

The comment in update-cache.c reads:
/*
  * We fundamentally don't like some paths: we don't want
  * dot or dot-dot anywhere, and in fact, we don't even want
  * any other dot-files (.git or anything else). They
  * are hidden, for chist sake.
  *
  * Also, we don't want double slashes or slashes at the
  * end that can make pathnames ambiguous.
  */

It could be argued that './' is a special case... but at the moment this 
is definitely a designed 'feature' not a 'bug'.
  --scott

BLUEBIRD SEQUIN SECANT Waihopai Honduras KUDOVE genetic KUJUMP SCRANTON 
DES AMLASH Indonesia SLINC cracking ESMERALDITE mustard Uzi KUSODA
                          ( http://cscott.net/ )

Re: [PATCH] Some documentation...

[David Greaves]

C. Scott Ananian wrote:
> On Wed, 20 Apr 2005, David Greaves wrote:
> 
>> In doing this I noticed a couple of points:
>> * update-cache won't accept ./file or fred/./file
> 
> 
> The comment in update-cache.c reads:
> /*
>  * We fundamentally don't like some paths: we don't want
>  * dot or dot-dot anywhere, and in fact, we don't even want
>  * any other dot-files (.git or anything else). They
>  * are hidden, for chist sake.
>  *
>  * Also, we don't want double slashes or slashes at the
>  * end that can make pathnames ambiguous.
>  */
> 
> It could be argued that './' is a special case... but at the moment this 
> is definitely a designed 'feature' not a 'bug'.

Indeed - I've been reading the code to document it as correctly as possible.

But I actually found this by running:

   find . -type f | xargs git add

for a new project - so I'd class it as user unfriendly...
Yes, I know how to get round it :)

I have ensured that my next perl version of gitadd.pl (that I submitted 
to Petr) doesn't allow these files to be added - and it could even 
cleanse leading ./ and any /./ constructs.

So maybe it's left as documented behaviour and higher level tools must 
manage the data they feed to it...

I hope it's useful to raise these niggles now before changing them is 
too hard.

David

-- 

Re: [PATCH] Some documentation...

[Linus Torvalds]

On Wed, 20 Apr 2005, David Greaves wrote:
> 
> So maybe it's left as documented behaviour and higher level tools must 
> manage the data they feed to it...

That was the plan.

I agree that "find . -type f | xargs update-cache --add --" in _theory_ is
a nice thing to do. But in practice, you want to make sure that find 
doesn't incldue the ".git" directory and that we always use the canonical 
names for all files etc etc.

I could do it in the low-level tools (ie do pathname cleanup there), and
indeed I did exactly that in the original code sequence. However, it very
quickly became obvious that the low-level code really doesn't want to
care, and that it's a lot easier to just do it at a higher level when 
necessary.

For example, if you have to add a sed-script or something that just 
removes '^./' and "^.git/", then that's trivial to do, and it leaves the 
core tools with a very clear agenda in life.

		Linus