This has some useful material that fills gaps in the existing
documentation.  We need to think a little more about the intended
audience, and about how to fit it in with existing documentation.

On Thu, Nov 16, 2006 at 05:17:01PM -0500, linux@horizon.com wrote:
quoted text
> * A brief digression on command names.
> 
> Originally, all git commands were named "git-foo".  When there got to
> be over a hundred, people started complaining about the clutter in
> /usr/bin.  After some discussion, the following solution was reached:
> 
> - It's now possible to place all of the git-foo commands into a separate
>   directory.  (Despite the complaints, not too many people are doing it
>   yet.)
> - One option for git users is to add that directory to their $PATH.
> - Another is provided by a wrapper called just "git".  It's intended to
>   live in a public directory like /usr/bin, and knows the location of
>   the separate directory.  When you type "git foo", it finds and executes
>   "git-foo".
> - Some simple commands are built into the git wrapper.  When you type
>   "git add", it just does it internally.  (On the git mailing list,
>   you will see patches like "make git diff a builtin"; this is what
>   they're talking about.)
> - For compatibility, for each builtin, there is a "git-add" file,
>   which is just a link to the "git" wrapper.  It looks at the name it
>   was invoked as to figure out what it should do.
> 
> The one confusing thing is that, although people usually type "git foo"
> in examples, they're interchangeable in practice.  I go back and forth
> for no good reason.  The main caveat is that to get the man page, you
> still need to type "man git-foo".  Fortunately, there are two other ways
> to get the man page:
> 
> 	1) "git help foo"
> 	2) "git foo --help"
> 
> Git doesn't have a specialized built-in help system; it just shows you
> the man pages.

Who's the audience for the above?  I can see that it's useful for
administrators, who may need help deciding how to install stuff, and for
developers, who need to know where the heck the code for "git-add" came
from.  But the case I'm most interested in is the user whose
distribution installs git for them, in which case I think the above
could be distilled down to:

	- "git-foo" and "git foo" can be used interchangeably.
	- Documentation for the command foo is available from any of
		- man git-foo
		- git help foo
		- git foo --help

Then the additional details above could be postponed to a later part of
the documentation.

quoted text
> One outstanding problem with git's man pages is that often the most detail
> is in the command page that was written first, not the user-friendly
> one that you should use.  For example, there are a number of special
> cases of the "git diff" command that were written first, and the man
> pages for these commands (git-diff-index, git-diff-files, git-diff-tree,
> and git-diff-stages) are considerably more informative than the page for
> plain git-diff, even though that's the command that you should use 99%
> of the time.

I agree that that's helpful.  Though we should probably also be working
on the man pages to make this organization clearer.

quoted text
> As you recall from Git 101

Obviously a more specific reference would be more useful here--if
there's nothing useful to point to among the existing documentation, we
should figure out how to fix that problem.

That might also remove the need for some of the recap that follows.

quoted text
> there are exactly four kinds of objects in
> Git's object database.  All of them have globally unique 40-character hex
....


quoted text
> Finally, there are references, stored in the .git/refs directory.
> These are the human-readable names associated with commits, and the
> "root set" from which all other commits should be reachable.

This is good; a comprehensive discussion of references will fill a gap
in the current documentation.

....

quoted text
> * Naming revisions
> 
> CVS encourages you to tag like crazy, because the only other way to
> find a given revision is by date.  Git makes it a lot easier, so most
> revisions don't need names.
> 
> You can find a full description in the git-rev-parse man page, but here's
> a summary.

This has a lot more overlap with existing documentation.  The extra
detail is useful, but we need to decide what our audience and goal is
here, to decide exactly what niche we're trying to fill between the
brief stuff that's in the tutorial part I and the details in
"man git-rev-parse".

quoted text
> * Converting between names
> 
> Git has two helpers (programs designed mainly for use in shell scripts)
> to convert between global object IDs and human-readable names.
> 
> The first is git-rev-parse.  This is a general git shell script helper,
> which validates the command line and converts object names to absolute
> object IDs.  Its man page has a detailed description of the object
> name syntax.
> 
> The second is git-name-rev, which converts the other way around.  It's
> particularly useful for seeing which tags a given commit falls between.

Also discuss git-describe?

quoted text
> * The three uses of "git checkout"

Obviously there's a lot of overlap here with "man git-checkout".  What's
the goal here?  Maybe this should just be worked in to a revision of
that man page?

quoted text
> * Deleting branches
> 
> "git branch -d <head>" is safe.  It deletes the given <head>, but first
> it checks that the commit is reachable some other way.  That is, you
> merged the branch in somewhere, or you never did any edits on that branch.

It only checks whether the head of the branch to delete is reachable
from the *current* branch.  The man page could be clearer here.

....

quoted text
> * Examining history: git-log and git-rev-list

Yep, we should definitely have a good long chapter just devoted to
history examination.  Most of it could be just cool examples, so it
would be fun.

Note some of this is done in the last half of cvs-migration.txt; we
should mine that section for whatever's useful and then replace by a
reference to the new chapter.

quoted text
> * History diagrams
...

quoted text
> * Trivial merges: fast-forward and already up-to-date.

These two sections are useful, yep.

quoted text
> * Exchanging work with other repositories, part II: git-push

There's a lot of overlap here with cvs-migration.txt.  Maybe some better
organization is needed to make that more prominent.

quoted text
> The details are too advanced for this discussion, but the default
> "recursive" merge strategy that git uses solves the answer by merging
> a and b into a temporary commit and using *that* as the merge base.

I'm tempted to ignore any description of the merge strategy, or postpone
it till later; as a first pass I think it's better just to say "obvious
cases will be handled automatically, and you'll be prompted for
comments."  Only other SCM developers are going to wonder how you handle
the corner cases.

quoted text
> * When merging goes wrong

But yes, I think people could use more help on how to resolve merges.

quoted text
> * Test merging
...
quoted text
> * Cherry picking
...
quoted text
> * Rebasing

Yup, I agree that that's good material to cover together.

--b.
-
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