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

[Jakub Narebski <jnareb@gmail.com>]

On Thu, Apr 03, 2007, Junio C Hamano wrote:
> 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'd rather not write about somthing I don't personally use.
But I can add one sentence mentioning detached head as an
alternative to "checkout -b tmp", "reset --hard" for sightseeing.
See also below.
 
>                                          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.

If I remember correctly I have added this note because of using
"git checkout -b new remotes/branch" (or tag) together with
"git reset --hard tag" for sight-seeing.
 
>> * 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.

So perhaps we should use this syntax in Git User's Manual?
 
>> * 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.

I was referring to the following fragment:

  As with git-fetch, git-push will complain if this does not result in
  a <<fast-forwards,fast forward>>.  Normally this is a sign of
  something wrong.  However, if you are sure you know what you're
  doing, you may force git-push to perform the update anyway by
  proceeding the branch name by a plus sign:

  -------------------------------------------------
  $ git push ssh://yourserver.com/~you/proj.git +master
  -------------------------------------------------

I'd like to have note here that if receive.denyNonFastForwards is set
on remote repository side (and it is set by default when initializing
shared repository), then you would not be able to force non fast-forward
push. Just to avoid potential confusion (why it is not accepting push?).
 
>> * 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.

It would be enough to have one sentence mentioning it, like e.g.
"Use 'git rebase --merge' if rebased commits include renames",
or something like that.
 
> 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.

Well, perhaps in "Advanced..." section it should be mentioned
that you can use 'git cherry-pick --no-commit' to concatenate
together some commits (and 'git merge --squash' to concatenate
whole branch to single commit).

Chosing "cherry-pick -n + commit" vs "cherry-pick + commit --amend"
is IMVHO a matter of taste; I think commit --amend is encouraged.

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

I was thinking about adding a sentence that you can have multiple
root commits in repository, and usually they are result of joining
two projects (git can join projects, which is a plus), or rather
including one project in the other.

Git User's Manual says:

  As a special case, a commit object with no parents is called the
  "root" object, and is the point of an initial project commit.  Each
  project must have at least one root, and while you can tie several
  different root objects together into one project by creating a commit
  object which has two or more separate roots as its ultimate parents,
  that's probably just going to confuse people.  So aim for the notion
  of "one root object per project", even if git itself does not enforce
  that.

I'd rather have this softened: try do not use it for the sake of using 
it, but joining projects (swallowing other project) results in multiple 
roots.

-- 
Jakub Narebski
ShadeHawk on #git
Poland