Theodore Tso <tytso@mit.edu> writes:

quoted text
> 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>.


-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html