From: Junio C Hamano <junkio@cox.net>
Date: Sun, 01 May 2005 19:27:23 GMT
Subject: Re: Quick command reference
Message-ID: <7v4qdmu4pw.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <42750D06.70004@dgreaves.com>

>>>>> "DG" == David Greaves <david@dgreaves.com> writes:

After I sent my endorsements, I noticed some nits so I pick them
here.  As you already know, you would also need to adjust to the
big git-* renaming.

DG> 	[Eventually may be replaced with <tree> if <tree> means
DG> 	<tree/commit> in all commands]

Probably not.  I think commit-tree should insist on its first
parameter being a tree not a commit for example, so I would drop
this comment.

Also tags are included in tree/commit class for some but
probably not all commands these days.  How about coming up with
a short-and-sweet name like <tree-id> and use it instead of
<tree/commit>?  You would need <commit-id> as well because tags
can be auto-dereferenced to commits by certain commands.

DG> <type>
DG> 	Indicates that an object type is required.
DG> 	Currently one of: blob/tree/commit

That's:

	Currently one of: blob/commit/tag/tree

DG> <file>
DG> 	Indicates a filename - often includes leading path
DG> <path>
DG> 	Indicates the path of a file (is this ever useful?)

I do not know what you wanted to distinguish by having separate
<file> and <path>.  There is only one thing.

We may want to mention that Core GIT expects the commands to run
from the directory that corresponds to the root level of the
tree structure GIT_INDEX_FILE describes, and the path/file
(whichever name you pick) are expected to be relative to that
directory.  No absolute paths, no ./relative paths with leading
dot-slash.

DG> ################################################################
DG> cat-file
DG> 	cat-file (-t | <type>) <object>
DG> ...
DG> <type>
DG> 	One of: blob/tree/commit
DG> ...
DG> Output
DG> If -t is specified, one of:
DG>         blob/tree/commit

Let's not list the type but refer the reader to the top part of
the document that lists the type.

DG> ################################################################
DG> checkout-cache
DG> ... Note that the file contents are
DG> restored - NOT the file permissions.
DG> ??? l 58 checkout-cache.c says restore executable bit.

So which is correct?

DG> ################################################################
DG> diff-tree-helper
DG> 	diff-tree-helper [-z]

Update:
	diff-tree-helper [-z] [-R]

Add:
        -R	generate the patch in reverse.

DG> ################################################################
DG> fsck-cache
DG> 	fsck-cache [[--unreachable] <commit>*]

--root?

DG> ################################################################
DG> show-diff
DG> 	show-diff [-p] [-q] [-s] [-z] [paths...]

After big git-* rename this became git-diff-files; just to keep
an eye on when you do the updates.

DG> ################################################################
DG> show-files

And this one is now git-ls-files.

DG> ################################################################
DG> unpack-file
DG> 	unpack-file <blob>

Add:

    Note that the temporary file is created with mkstemp(3) and it
    would have permission 0600 or 0666 depending on your glibc
    version.  Make sure to fix the permission if you use this in
    your script.

DG> ################################################################
DG> Generating patches

Please drop the following part.  GIT_DIFF_CMD is not supported
anymore:

DG>    The first part of the above command-line can be customized via
DG>    the environment variable GIT_DIFF_CMD...
DG>    ... 
DG>    Caution:  Do not use more than two '%s' in GIT_DIFF_CMD.

Drop it also from "git Environment Variables" section.