patchDocumentation: A few minor fixes to Git User's Manual

Mainly consistent usage of "git command" and not "git-command" syntax

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
A few [shorthand] comments about Git User's Manual:

* no "detached head" feature (since 1.5.0.5 at least)
* git branch --track as shorthand (for 1.5.1)
* uses ssh://host/path syntax instead of scp-like host:path
  (which one is preferred? documentation has URL-like first)
* no mention of receive.denyNonFastForwards (in about push)
* inconsistent use of header levels
        Level 0 (top level):     ======================                              
        Level 1:                 ----------------------                              
        Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~                              
        Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^                              
        Level 4 (bottom level):  ++++++++++++++++++++++
* no git rebase --skip (e.g. if patch was applied, but
  duplication was not detected, or patch is no longer needed)
* no git rebase --merge (e.g. renames)
* git cherry-pick --no-commit + git commit, instead of
  git cherry-pick + git commit --amend
* legitimate use of multiple root commits: joining projects
  (e.g. git = git-core + git-tools (mail) + gitk + gitweb + git-gui)
* note that description of git internals would use plumbing
  commands (e.g. git-update-index instead of git-add / git-rm)
* blob object: git-add and git-show instead of git-update-index
  and git-cat-file? (plumbing vs porcelain)
* tree object: user usually do not use git-write-tree (plumbing) (?)
* commit object: "read SCM's", "idiotic file manager" -- git has
  now enough porcelain to be considered full fledged SCM (in "Note
  on commits"). needs rewording?
* tag object: porcelain to create tag is git-tag, and you can use
  git tag -v to verify a tag (plumbing vs porcelain)
* interchanging old name "directory cache" with new name "index"
* git update-index --force-remove to make file untracked
* very useful git-cat-file -p
* git-rev-parse <commitname>^{tree} instead of 
  git-cat-file commit <commitname> | head -1
* git-cat-file blob :1:hello.c >hello.c~1, git-merge-file
  (and git-mergetool if discussion was not so plumbing-ish)

 Documentation/user-manual.txt |   20 ++++++++++----------
 1 files changed, 10 insertions(+), 10 deletions(-)

On Tue, Apr 03, 2007 at 06:27:28PM +0200, Jakub Narebski wrote:

Looks good, thanks!

And thanks very much for the comments.

Have you found internal inconsistencies, or are you just referring to the fact that it's using different syntax from the default?

My original intention was to suck in other articles under Documentation/ as chapters. Shifting all the headers by one allows us to do that, at least initially, by just including the articles without modification. The glossary is the only thing we're currently using that way, though.

The "Git interals" chapter is obviously most taken from the README, which has gotten out of date in a few places.

My vague medium-term plan is to revise that chapter and then merge tutorial-2.txt into it, and maybe core-tutorial too, but I haven't had time to work on it recently. (Any help appreciated.)

I'd kinda like to remove all the tutorials some day and absorb them into the manual instead, but maybe that would be unpopular.

--b.

On Tue, Apr 03, 2007, J. Bruce Fields wrote:

[...]

Both, but more the fact that I haven't noticed that user-manual uses different syntax (____ and not ==== is Level 0), and that I mistook ____ for ---- (perhaps #### would be better, if it is possible), but also the fact that parts Git User's Manual is composed of use different sectioning.

I'd rather keep the tutorials, perhaps making them more tutorial-ish, and adding proposed but not as a patch and not included "Branching and Merging" tutorial, and making Git User's Manual more a reference material.

Jakub Narebski <jnareb@gmail.com> writes:

The patch part looks good so I'll be applying it before 1.5.1, Ok?

On Tue, Apr 03, 2007 at 11:39:48AM -0700, Junio C Hamano wrote:

Definitely.  If you'd like:

Acked-by: J. Bruce Fields <bfields@citi.umich.edu>

--b.

Jakub Narebski <jnareb@gmail.com> writes:

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.

My impression is that site:path is preferred.

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 am not sure what you are getting at.  

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.

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.

On Thu, Apr 03, 2007, Junio C Hamano wrote:

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.
 

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.
 

So perhaps we should use this syntax in Git User's Manual?
 

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?).
 

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.
 

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.

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.