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

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

[Jakub Narebski]

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(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c49e69..574e9c0 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -84,7 +84,7 @@ $ git branch -r		# list
   origin/master
   origin/next
   ...
-$ git branch checkout -b masterwork origin/master
+$ git checkout -b masterwork origin/master
 -----------------------------------------------
 
 Fetch a branch from a different repository, and give it a new
@@ -155,8 +155,8 @@ Make sure git knows who to blame:
 ------------------------------------------------
 $ cat >~/.gitconfig <<\EOF
 [user]
-name = Your Name Comes Here
-email = you@yourdomain.example.com
+	name = Your Name Comes Here
+	email = you@yourdomain.example.com
 EOF
 ------------------------------------------------
 
@@ -195,7 +195,7 @@ Importing or exporting patches:
 -----------------------------------------------
 $ git format-patch origin..HEAD # format a patch for each commit
 				# in HEAD but not in origin
-$ git-am mbox # import patches from the mailbox "mbox"
+$ git am mbox # import patches from the mailbox "mbox"
 -----------------------------------------------
 
 Fetch a branch in a different git repository, then merge into the
@@ -579,7 +579,7 @@ cloned from, using gitlink:git-remote[1]:
 
 -------------------------------------------------
 $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
-$ git fetch
+$ git fetch linux-nfs
 * refs/remotes/linux-nfs/master: storing branch 'master' ...
   commit: bf81b46
 -------------------------------------------------
@@ -680,7 +680,7 @@ occasionally you may land on a commit that broke something unrelated;
 run
 
 -------------------------------------------------
-$ git bisect-visualize
+$ git bisect visualize
 -------------------------------------------------
 
 which will run gitk and label the commit it chose with a marker that
@@ -765,7 +765,7 @@ We can also create a tag to refer to a particular commit; after
 running
 
 -------------------------------------------------
-$ git-tag stable-1 1b2e1d63ff
+$ git tag stable-1 1b2e1d63ff
 -------------------------------------------------
 
 You can use stable-1 to refer to the commit 1b2e1d63ff.
@@ -909,7 +909,7 @@ name based on any tag it finds pointing to one of the commit's
 descendants:
 
 -------------------------------------------------
-$ git name-rev e05db0fd
+$ git name-rev --tags e05db0fd
 e05db0fd tags/v1.5.0-rc1^0~23
 -------------------------------------------------
 
@@ -918,7 +918,7 @@ revision using a tag on which the given commit is based:
 
 -------------------------------------------------
 $ git describe e05db0fd
-v1.5.0-rc0-ge05db0f
+v1.5.0-rc0-260-ge05db0f
 -------------------------------------------------
 
 but that may sometimes help you guess which tags might come after the
@@ -1861,7 +1861,7 @@ Allow web browsing of a repository
 
 The gitweb cgi script provides users an easy way to browse your
 project's files and history without having to install git; see the file
-gitweb/README in the git source tree for instructions on setting it up.
+gitweb/INSTALL in the git source tree for instructions on setting it up.
 
 Examples
 --------
-- 
1.5.0.5

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

[J. Bruce Fields]

On Tue, Apr 03, 2007 at 06:27:28PM +0200, Jakub Narebski wrote:
> Mainly consistent usage of "git command" and not "git-command" syntax

Looks good, thanks!

> A few [shorthand] comments about Git User's Manual:

And thanks very much for the comments.

> * inconsistent use of header levels
>         Level 0 (top level):     ======================
>         Level 1:                 ----------------------
>         Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
>         Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
>         Level 4 (bottom level):  ++++++++++++++++++++++

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.

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

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Mainly consistent usage of "git command" and not "git-command" syntax
>
> Signed-off-by: Jakub Narebski <jnareb@gmail.com>

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

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

[J. Bruce Fields]

On Tue, Apr 03, 2007 at 11:39:48AM -0700, Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > Mainly consistent usage of "git command" and not "git-command" syntax
> >
> > Signed-off-by: Jakub Narebski <jnareb@gmail.com>
> 
> The patch part looks good so I'll be applying it before 1.5.1, Ok?

Definitely.  If you'd like:

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

--b.

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

[Junio C Hamano]

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.

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

[Jakub Narebski]

On Tue, Apr 03, 2007, J. Bruce Fields wrote:
> On Tue, Apr 03, 2007 at 06:27:28PM +0200, Jakub Narebski wrote:
>>
>> A few [shorthand] comments about Git User's Manual:
[...]
>> * inconsistent use of header levels
>>         Level 0 (top level):     ======================
>>         Level 1:                 ----------------------
>>         Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
>>         Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
>>         Level 4 (bottom level):  ++++++++++++++++++++++
> 
> Have you found internal inconsistencies, or are you just referring to
> the fact that it's using different syntax from the default?

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 kinda like to remove all the tutorials some day and absorb them into
> the manual instead, but maybe that would be unpopular.

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
Poland

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

[Jakub Narebski]

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