Re: [PATCH] Documentation: A few minor fixes to Git User's Manual

[Junio C Hamano <junkio@cox.net>]

Jakub Narebski <jnareb@gmail.com> writes:

> * no "detached head" feature (since 1.5.0.5 at least)

That is a 1.5.0 feature.

Care to volunteer to write that section?  I think illustrating
what you would want to achieve by detaching your HEAD would be
useful, and I offhand know of two different uses:

 - Sightseeing.  You do not intend to build on, but seek around
   to see what was there in the past.  Checking out a tag or a
   remote branch falls into this.

 - Rebuilding history.  When you want to futz with a commit 5
   revs ago, you would detach your HEAD to that commit, fix it
   up, and rebase the original branch on top of that detached
   HEAD.

I am sure people may have invented more creative ways to use it.
The topic probably belongs to "advanced user's manual", though.

> * uses ssh://host/path syntax instead of scp-like host:path
>   (which one is preferred? documentation has URL-like first)

My impression is that site:path is preferred.

> * no mention of receive.denyNonFastForwards (in about push)

I think the "Setting up a shared repository" section refers most
of the material to cvs-migration.txt, so you probably want to
add a sentence to "Advanced Shared Repository Management"
section in the latter.

> * inconsistent use of header levels

I am not sure what you are getting at.  

> * no git rebase --merge (e.g. renames)
> * git cherry-pick --no-commit + git commit, instead of
>   git cherry-pick + git commit --amend

It usually is not a good idea for a manual to show two ways to
do the same thing without explaining pros and cons.

I typically use rebase *without* --merge because it tends to be
faster (recently 'mailinfo' was broken for i18n contents, and I
had to use "rebase --merge" until it was fixed; now I can go
back to my old ways of running it without --merge ;-)).  I think
the only reason to use --merge is when you want the rename thing
in merge-recursive.

I do not think "cherry-pick -n + commit" vs "cherry-pick +
commit --amend" is an interesting contrast for a single commit.
Squashing more than one commit is why you would want to pick
without committing, which you cannot do with the latter.  So
they are not "instead of" -- they serve different purposes.

> * legitimate use of multiple root commits: joining projects
>   (e.g. git = git-core + git-tools (mail) + gitk + gitweb + git-gui)

I am not sure if you would even need to talk about it.  As long
as the document does not say "you shouldn't have more than one
root", I think we are Ok.