Re: [RFC] git-add update with all-0 object

From: Junio C Hamano <junkio@cox.net>
Date: Dec 1, 2006, 06:20 UTC
Message-ID: <7vhcwgcf39.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20061201045727.GA22622@thunk.org>

Theodore Tso <tytso@mit.edu> writes:

Show 9 quoted lines

> The question then is how can we fix the "git diff" man page, and how
> do we explain "git diff" in a tutorial so that users can understand
> what in the world does it do?  For a starting point, I'd recommend
> moving the EXAMPLES to the beginning of the man page, and moving the
> any mention of git-diff-index, git-diff-files, and git-diff-tree to
> the very end of the man page, and to put the most commonly used
> options in the git-diff man page, so that most users don't have to
> look at the low-level plumbing man pages to figure out how the
> high-level git-diff works.

All good points. The only slight worry I have is that just moving EXAMPLE up deviates from the traditional UNIX manpage order of presenting information.

I think the plumbing manuals can (and probably should) stay as the technical manual for Porcelain writers. "git diff", "git add" and friends that are clearly Porcelain should talk about what it does in the terms of end user operation in the DESCRIPTION section and puts less stress on how things work behind the scene in technical terms. For example, from git-diff(1):

        DESCRIPTION
        -----------
        Show changes between two trees, a tree and the working tree, a
        tree and the index file, or the index file and the working tree.
        The combination of what is compared with what is determined by
        the number of trees given to the command.

That may be an accurate description of what the command does in technical terms, but it does not tell why the user may want to compare "a tree and the working tree". The users would want to know which case applies to their current situation and we should make it easier for them to find that information.

For example, although --cached is technically speaking one of the --diff-options, it should be separated out from other options when we talk about 'git-diff'. Also, although 'git-diff' is designed to work on tree-ish, Porcelain users will use with commit-ish (either a commit or an annotated signed tag that points at a commit) 99.9% of the time, so we should mention <tree-ish> at the end as a sidenote and talk about <commit>.

	DESCRIPTION
	-----------
	This command shows changes between four combinations 
	of states.

	* 'git-diff' [--options] [--] [<path>...]

          is to see the changes you made relative to the index
          (staging area for the next commit).  In other words, the
          differences are what you _could_ tell git to further add
          to the index but you still haven't.  You can stage
          these changes by using gitlink:git-update-index[1].

        * 'git-diff' [--options] --cached [<commit>] [--] [<path>...]

          is to see the changes you staged for the next commit
          relative to the named <tree-ish>.  Typically you would
          want comparison with the latest commit, so if you do
          not give <commit>, it defaults to HEAD.

        * 'git-diff' [--options] <commit> -- [<path>...]

          is to see the changes you have in your working tree,
          regardless of you staged them or not, relative to the
          named <commit>.

	* 'git-diff' [--options] <commit> <commit> -- [<path>...]

	  is to see the changes between two <commit>.

	Just in case if you are doing something exotic, it
        should be noted that all of the <commit> in the above
        descriptoin can be any <tree-ish>.