Documentation (mostly user manual) patches

Documentation (mostly user manual) patches

[J. Bruce Fields]

Sorry for the long silence.  You can also get these by pulling from

	git://linux-nfs.org/~bfields/git.git

if you'd prefer.

--b.

[PATCH] Documentation: mention module option to git-cvsimport

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

The git-cvsimport argument that specifies a cvs module to import should
probably be included in the default example.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/cvs-migration.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 764cc56..3b6b494 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -109,7 +109,7 @@ sure it is in your path.  Then cd to a checked out CVS working directory
 of the project you are interested in and run gitlink:git-cvsimport[1]:
 
 -------------------------------------------
-$ git cvsimport -C <destination>
+$ git cvsimport -C <destination> <module>
 -------------------------------------------
 
 This puts a git archive of the named CVS module in the directory
-- 
1.5.0.gb75812-dirty

[PATCH] user-manual: reset to ORIG_HEAD not HEAD to undo merge

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

As Linus pointed out recently on the mailing list,

	git reset --hard HEAD^

doesn't undo a merge in the case where the merge did a fast-forward.  So
the rcommendation here is a little dangerous.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 34e9651..0979211 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1255,7 +1255,7 @@ $ git reset --hard HEAD
 Or, if you've already commited the merge that you want to throw away,
 
 -------------------------------------------------
-$ git reset --hard HEAD^
+$ git reset --hard ORIG_HEAD
 -------------------------------------------------
 
 However, this last command can be dangerous in some cases--never
-- 
1.5.0.gb75812-dirty

[PATCH] user-manual: ensure generated manual references stylesheet

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

The generated user manual is rather hard to read thanks to the lack of
the css that's supposed to be included from docbook-xsl.css.

I'm totally ignorant of the toolchain; grubbing through xmlto and
related scripts, the easiest way I could find to ensure that the
generated html links to the stylesheet is by calling xsltproc directly.
Maybe there's some better way.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/Makefile |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b6d1d88..7c1c9e1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -105,8 +105,11 @@ clean:
 user-manual.xml: user-manual.txt user-manual.conf
 	$(ASCIIDOC) -b docbook -d book $<
 
+XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
+XSLTOPTS = --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css
+
 user-manual.html: user-manual.xml
-	xmlto html-nochunks $<
+	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
 glossary.html : glossary.txt sort_glossary.pl
 	cat $< | \
-- 
1.5.0.gb75812-dirty

[PATCH] user-manual: insert earlier of mention content-addressable architecture

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

The content-addressable design is too important not to be worth at least
a brief mention a little earlier on.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |   24 +++++++++++++++---------
 1 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0979211..33f8a72 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -391,15 +391,20 @@ index 8be626f..d7aac9d 100644
 As you can see, a commit shows who made the latest change, what they
 did, and why.
 
-Every commit has a 40-hexdigit id, sometimes called the "object name"
-or the "SHA1 id", shown on the first line of the "git show" output.
-You can usually refer to a commit by a shorter name, such as a tag or a
-branch name, but this longer name can also be useful.  Most
-importantly, it is a globally unique name for this commit: so if you
-tell somebody else the object name (for example in email), then you are
-guaranteed that name will refer to the same commit in their repository
-that it does in yours (assuming their repository has that commit at
-all).
+Every commit has a 40-hexdigit id, sometimes called the "object name" or the
+"SHA1 id", shown on the first line of the "git show" output.  You can usually
+refer to a commit by a shorter name, such as a tag or a branch name, but this
+longer name can also be useful.  Most importantly, it is a globally unique
+name for this commit: so if you tell somebody else the object name (for
+example in email), then you are guaranteed that name will refer to the same
+commit in their repository that it does in yours (assuming their repository
+has that commit at all).  Since the object name is computed as a hash over the
+contents of the commit, you are guaranteed that the commit can never change
+without its name also changing.
+
+In fact, in <<git-internals>> we shall see that everything stored in git
+history, including file data and directory contents, is stored in an object
+with a name that is a hash of its contents.
 
 Understanding history: commits, parents, and reachability
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2155,6 +2160,7 @@ See gitlink:git-config[1] for more details on the configuration
 options mentioned above.
 
 
+[[git-internals]]
 Git internals
 =============
 
-- 
1.5.0.gb75812-dirty

[PATCH] user-manual: how to replace commits older than most recent

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

"Modifying" an old commit by checking it out, --amend'ing it, then
rebasing on top of it, is a slightly cumbersome technique, but I've
found it useful frequently enough to make it seem worth documenting.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |   46 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 33f8a72..907f122 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1333,6 +1333,7 @@ with the changes to be reverted, then you will be asked to fix
 conflicts manually, just as in the case of <<resolving-a-merge,
 resolving a merge>>.
 
+[[fixing-a-mistake-by-editing-history]]
 Fixing a mistake by editing history
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1935,6 +1936,51 @@ return mywork to the state it had before you started the rebase:
 $ git rebase --abort
 -------------------------------------------------
 
+Modifying a single commit
+-------------------------
+
+We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the
+most recent commit using
+
+-------------------------------------------------
+$ git commit --amend
+-------------------------------------------------
+
+which will replace the old commit by a new commit incorporating your
+changes, giving you a chance to edit the old commit message first.
+
+You can also use a combination of this and gitlink:git-rebase[1] to edit
+commits further back in your history.  First, tag the problematic commit with
+
+-------------------------------------------------
+$ git tag bad mywork~5
+-------------------------------------------------
+
+(Either gitk or git-log may be useful for finding the commit.)
+
+Then check out a new branch at that commit, edit it, and rebase the rest of
+the series on top of it:
+
+-------------------------------------------------
+$ git checkout -b TMP bad
+$ # make changes here and update the index
+$ git commit --amend
+$ git rebase --onto TMP bad mywork
+-------------------------------------------------
+
+When you're done, you'll be left with mywork checked out, with the top patches
+on mywork reapplied on top of the modified commit you created in TMP.  You can
+then clean up with
+
+-------------------------------------------------
+$ git branch -d TMP
+$ git tag -d bad
+-------------------------------------------------
+
+Note that the immutable nature of git history means that you haven't really
+"modified" existing commits; instead, you have replaced the old commits with
+new commits having new object names.
+
 Reordering or selecting from a patch series
 -------------------------------------------
 
-- 
1.5.0.gb75812-dirty

[PATCH] user-manual: more detailed merge discussion

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Add more details on conflict, including brief discussion of file stages.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |  102 +++++++++++++++++++++++++++++++----------
 1 files changed, 77 insertions(+), 25 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 907f122..ffd673e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1168,18 +1168,46 @@ the working tree in a special state that gives you all the
 information you need to help resolve the merge.
 
 Files with conflicts are marked specially in the index, so until you
-resolve the problem and update the index, git commit will fail:
+resolve the problem and update the index, gitlink:git-commit[1] will
+fail:
 
 -------------------------------------------------
 $ git commit
 file.txt: needs merge
 -------------------------------------------------
 
-Also, git status will list those files as "unmerged".
+Also, gitlink:git-status[1] will list those files as "unmerged", and the
+files with conflicts will have conflict markers added, like this:
+
+-------------------------------------------------
+<<<<<<< HEAD:file.txt
+Hello world
+=======
+Goodbye
+>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
+-------------------------------------------------
+
+All you need to do is edit the files to resolve the conflicts, and then
+
+-------------------------------------------------
+$ git add file.txt
+$ git commit
+-------------------------------------------------
+
+Note that the commit message will already be filled in for you with
+some information about the merge.  Normally you can just use this
+default message unchanged, but you may add additional commentary of
+your own if desired.
+
+The above is all you need to know to resolve a simple merge.  But git
+also provides more information to help resolve conflicts:
+
+Getting conflict-resolution help during a merge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All of the changes that git was able to merge automatically are
 already added to the index file, so gitlink:git-diff[1] shows only
-the conflicts.  Also, it uses a somewhat unusual syntax:
+the conflicts.  It uses an unusual syntax:
 
 -------------------------------------------------
 $ git diff
@@ -1200,14 +1228,32 @@ conflict will have two parents instead of the usual one: one parent
 will be HEAD, the tip of the current branch; the other will be the
 tip of the other branch, which is stored temporarily in MERGE_HEAD.
 
-The diff above shows the differences between the working-tree version
-of file.txt and two previous versions: one version from HEAD, and one
-from MERGE_HEAD.  So instead of preceding each line by a single "+"
-or "-", it now uses two columns: the first column is used for
-differences between the first parent and the working directory copy,
-and the second for differences between the second parent and the
-working directory copy.  Thus after resolving the conflict in the
-obvious way, the diff will look like:
+During the merge, the index holds three versions of each file.  Each of
+these three "file stages" represents a different version of the file:
+
+-------------------------------------------------
+$ git show :1:file.txt	# the file in a common ancestor of both branches
+$ git show :2:file.txt	# the version from HEAD, but including any
+			# nonconflicting changes from MERGE_HEAD
+$ git show :3:file.txt	# the version from MERGE_HEAD, but including any
+			# nonconflicting changes from HEAD.
+-------------------------------------------------
+
+Since the stage 2 and stage 3 versions have already been updated with
+nonconflicting changes, the only remaining differences between them are
+the important ones; thus gitlink:git-diff[1] can use the information in
+the index to show only those conflicts.
+
+The diff above shows the differences between the working-tree version of
+file.txt and the stage 2 and stage 3 versions.  So instead of preceding
+each line by a single "+" or "-", it now uses two columns: the first
+column is used for differences between the first parent and the working
+directory copy, and the second for differences between the second parent
+and the working directory copy.  (See the "COMBINED DIFF FORMAT" section
+of gitlink:git-diff-files[1] for a details of the format.)
+
+After resolving the conflict in the obvious way (but before updating the
+index), the diff will look like:
 
 -------------------------------------------------
 $ git diff
@@ -1225,26 +1271,37 @@ This shows that our resolved version deleted "Hello world" from the
 first parent, deleted "Goodbye" from the second parent, and added
 "Goodbye world", which was previously absent from both.
 
-The gitlink:git-log[1] command also provides special help for merges:
+Some special diff options allow diffing the working directory against
+any of these stages:
+
+-------------------------------------------------
+$ git diff -1 file.txt		# diff against stage 1
+$ git diff --base file.txt	# same as the above
+$ git diff -2 file.txt		# diff against stage 2
+$ git diff --ours file.txt	# same as the above
+$ git diff -3 file.txt		# diff against stage 3
+$ git diff --theirs file.txt	# same as the above.
+-------------------------------------------------
+
+The gitlink:git-log[1] and gitk[1] commands also provide special help
+for merges:
 
 -------------------------------------------------
 $ git log --merge
+$ gitk --merge
 -------------------------------------------------
 
-This will list all commits which exist only on HEAD or on MERGE_HEAD,
-and which touch an unmerged file.
+These will display all commits which exist only on HEAD or on
+MERGE_HEAD, and which touch an unmerged file.
 
-We can now add the resolved version to the index and commit:
+Each time you resolve the conflicts in a file and update the index:
 
 -------------------------------------------------
 $ git add file.txt
-$ git commit
 -------------------------------------------------
 
-Note that the commit message will already be filled in for you with
-some information about the merge.  Normally you can just use this
-default message unchanged, but you may add additional commentary of
-your own if desired.
+the different stages of that file will be "collapsed", after which
+git-diff will (by default) no longer show diffs for that file.
 
 [[undoing-a-merge]]
 undoing a merge
@@ -2988,11 +3045,6 @@ provides.
 Simplify beginning by suggesting disconnected head instead of
 temporary branch creation?
 
-Explain how to refer to file stages in the "how to resolve a merge"
-section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
-"git ls-files --unmerged --stage" thing is sorta useful too,
-actually.  And note gitk --merge.
-
 Add more good examples.  Entire sections of just cookbook examples
 might be a good idea; maybe make an "advanced examples" section a
 standard end-of-chapter section?
-- 
1.5.0.gb75812-dirty

[PATCH] glossary: Add definitions for dangling and unreachable objects

[J. Bruce Fields]

From: Yasushi SHOJI <yashi@atmark-techno.com>

Define "dangling" and "unreachable" objects.  Modified from original
text proposed by Yasushi Shoji.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/glossary.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt
index d20eb62..9f44624 100644
--- a/Documentation/glossary.txt
+++ b/Documentation/glossary.txt
@@ -73,6 +73,11 @@ DAG::
 	objects is acyclic (there is no chain which begins and ends with the
 	same object).
 
+dangling object::
+	An unreachable object which is not reachable even from other
+	unreachable objects; a dangling object has no references to it
+	from any reference or object in the repository.
+
 dircache::
 	You are *waaaaay* behind.
 
@@ -350,6 +355,10 @@ tag::
 unmerged index::
 	An index which contains unmerged index entries.
 
+unreachable object::
+	An object which is not reachable from a branch, tag, or any
+	other reference.
+
 working tree::
 	The set of files and directories currently being worked on,
 	i.e. you can work in your working tree without using git at all.
-- 
1.5.0.gb75812-dirty

Re: [PATCH] glossary: Add definitions for dangling and unreachable objects

[Yasushi SHOJI]

At Sun,  4 Mar 2007 16:59:16 -0500,
J. Bruce Fields wrote:
> 
> From: Yasushi SHOJI <yashi@atmark-techno.com>
> 
> Define "dangling" and "unreachable" objects.  Modified from original
> text proposed by Yasushi Shoji.
> 
> Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

If possible, please include

    http://article.gmane.org/gmane.comp.version-control.git/40662

that's the original. otherwise

Acked-by: Yasushi SHOJI <yashi@atmark-techno.com>

thanks,
-- 
         yashi

Re: [PATCH] user-manual: ensure generated manual references stylesheet

[Robert Pluim]

J. Bruce Fields <bfields <at> citi.umich.edu> writes:


> +XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
> +XSLTOPTS = --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css
> +
>  user-manual.html: user-manual.xml
> -	xmlto html-nochunks $<
> +	xsltproc $(XSLTOPTS) -o $ <at>  $(XSLT) $<

Does this actually work for you?  I get:

  xsltproc --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css -o
user-manual.html
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl user-manual.xml
  I/O error : Attempt to load network entity
http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
  warning: failed to load external entity
"http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
  cannot parse http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
  make[1]: *** [user-manual.html] Error 4


If I remove the --nonet it works fine.

Robert

-- 

Re: [PATCH] user-manual: ensure generated manual references stylesheet

[J. Bruce Fields]

On Fri, Mar 16, 2007 at 12:44:19PM +0000, Robert Pluim wrote:
> J. Bruce Fields <bfields <at> citi.umich.edu> writes:
> 
> 
> > +XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
> > +XSLTOPTS = --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css
> > +
> >  user-manual.html: user-manual.xml
> > -	xmlto html-nochunks $<
> > +	xsltproc $(XSLTOPTS) -o $ <at>  $(XSLT) $<
> 
> Does this actually work for you?  I get:
> 
>   xsltproc --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css -o
> user-manual.html
> http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl user-manual.xml
>   I/O error : Attempt to load network entity
> http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
>   warning: failed to load external entity
> "http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
>   cannot parse http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
>   make[1]: *** [user-manual.html] Error 4
> 
> 
> If I remove the --nonet it works fine.

Yes, it works for me.  From a quick strace, it appears to find the file
by opening /etc/xml/catalog, aplying some URL-rewriting rules found
there, then finding a file on my local filesystem under
/usr/share/sgml/docbook/.  Those files appear to be provided by a
package named docbook-style-xsl on my fedora box, and something called
docbook-xsl on my debian box.

I'd prefer the build not require network access, if possible.

--b.

Re: [PATCH] user-manual: ensure generated manual references stylesheet

[J. Bruce Fields]

On Fri, Mar 16, 2007 at 11:01:47AM -0400, Brian Gernhardt wrote:
> I remember running into huge issues with docbook and xmlto under  
> either Fink or MacPorts because it was still looking in /etc/xml/ 
> catalog.  IIRC, the --nonet flag disables network access but not  
> having it does not mean that you will access the network.  What  
> happens is that on machines with the xsl files installed, it will use  
> the local copy either way (via /etc/xml/catalog), but if you don't it  
> will go to the actual URL (which will die with --nonet).

Oh, OK, thanks for pointing that out.  So I agree then that --nonet
doesn't make sense.

> I  personally don't see a reason to use --nonet for everyone.  If a
> particular user doesn't want xsltproc hitting the 'net then they can
> use that option, but there's no reason to break the build for people
> who don't care.  Providing a user-configurable variable to pass
> options to xsltproc is probably a good idea anyway. (XSLTFLAGS,
> maybe?)

Eh, it doesn't sound like there's a real need for it for --nonet.  Is
there some other reason to do that?

--b.

Re: [PATCH] user-manual: ensure generated manual references stylesheet

[J. Bruce Fields]

On Fri, Mar 16, 2007 at 12:29:42PM -0400, Brian Gernhardt wrote:
> I've honestly never used it too much.  I got a distinct dislike for  
> docbook and xsltproc after trying to get it to work for a couple  
> days.

I understand.  The position of Chief Git Docbook Hacker is very much
open--I'm still pretty ignorant of that whole toolchain.

> As I recall there were some options for alternate/additional  
> catalogs and the like.  However, I mostly suggested it as a way to  
> let you (and others who want it) to use --nonet.

Nah, I probably just copied that --nonet from someplace else without
understanding it properly.

--b.

Re: Documentation (mostly user manual) patches

[Junio C Hamano]

"J. Bruce Fields" <bfields@citi.umich.edu> writes:

> Sorry for the long silence.  You can also get these by pulling from
>
> 	git://linux-nfs.org/~bfields/git.git
>
> if you'd prefer.

Thanks.  I pulled first, but ended up rebasing them on top of
'maint', as the updated manual is still perfectly applicable for
1.5.0 series.

If it is not too much to ask, I'd prefer future pull insns for
two branches from your side.  Please maintain a fork of my
'maint' and a fork of my 'master' on your side, and apply all
updates to the manual that is applicable to 1.5.0 series on your
'maint'.  If there are updates to the manual that talks about
new material that will appear in 1.5.1, merge your 'maint' to
your 'master' and then apply the updates there.

That way, I can continue pulling your 'maint' to my 'maint' to
keep 1.5.0 series alive without worrying about contaminating
'maint' with new material that should appear only in 1.5.1.  At
the same time, pulling your 'master' to my 'master' will not
miss any updates to 'maint' and the manual that ships with 1.5.1
will talk about new stuff as well.

Re: Documentation (mostly user manual) patches

[J. Bruce Fields]

On Sun, Mar 04, 2007 at 07:14:33PM -0800, Junio C Hamano wrote:
> Thanks.  I pulled first, but ended up rebasing them on top of
> 'maint', as the updated manual is still perfectly applicable for
> 1.5.0 series.

OK, thanks.

> If it is not too much to ask, I'd prefer future pull insns for
> two branches from your side.  Please maintain a fork of my
> 'maint' and a fork of my 'master' on your side, and apply all
> updates to the manual that is applicable to 1.5.0 series on your
> 'maint'.  If there are updates to the manual that talks about
> new material that will appear in 1.5.1, merge your 'maint' to
> your 'master' and then apply the updates there.

That sounds easy enough; will do.

--b.

Re: Documentation (mostly user manual) patches

[J. Bruce Fields]

> If it is not too much to ask, I'd prefer future pull insns for
> two branches from your side.  Please maintain a fork of my
> 'maint' and a fork of my 'master' on your side, and apply all
> updates to the manual that is applicable to 1.5.0 series on your
> 'maint'.  If there are updates to the manual that talks about
> new material that will appear in 1.5.1, merge your 'maint' to
> your 'master' and then apply the updates there.

OK, I hope I've understand what you're asking for: the following small
(mainly user-manual) fixes all make sense for both 1.5.0 and 1.5.1, so
(in addition to emailing them), I've applied them to the top of the
"maint" branch at:

	git://linux-nfs.org/~bfields/git.git

which is just a fork of your "maint".

I haven't done anything to my "master", since I've got nothing
1.5.1-specific, and since I assume you'll take care of pulling this
stuff into master some time later.

--b.

[PATCH 1/6] glossary: fix overoptimistic automatic linking of defined terms

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

The script sort_glossary.pl turns each use of "term" into a link to the
definition of "term".  To avoid mangling links like

	gitlink:git-term[1]

it doesn't replace any occurence of "term" preceded by "link:git-".
This fails for gitlink:git-symbolic-ref[1] when substituting for "ref".

So instead just refuse to replace anything preceded by a "-".
That could result in missing some opportunities, but that's a less
annoying error.

Actually I find the automatic substitution a little distracting; some
day maybe we should just run it once and commit the result, so it can
be hand-tuned.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/sort_glossary.pl |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl
index e0bc552..05dc7b2 100644
--- a/Documentation/sort_glossary.pl
+++ b/Documentation/sort_glossary.pl
@@ -48,7 +48,7 @@ This list is sorted alphabetically:
 ';
 
 @keys=sort {uc($a) cmp uc($b)} keys %terms;
-$pattern='(\b(?<!link:git-)'.join('\b|\b(?<!link:git-)',reverse @keys).'\b)';
+$pattern='(\b(?<!link:git-)'.join('\b|\b(?<!-)',reverse @keys).'\b)';
 foreach $key (@keys) {
 	$terms{$key}=~s/$pattern/sprintf "<<ref_".no_spaces($1).",$1>>";/eg;
 	print '[[ref_'.no_spaces($key).']]'.$key."::\n"
-- 
1.5.0.gb75812-dirty

[PATCH 2/6] user-manual: fix inconsistent example

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

The configuration file fragment here is inconsistent with the text
above.  Thanks to Ramsay Jones for the correction.

Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a5e7b53..8b5709b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -601,8 +601,8 @@ a new stanza:
 $ cat .git/config
 ...
 [remote "linux-nfs"]
-        url = git://linux-nfs.org/~bfields/git.git
-	fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
+	url = git://linux-nfs.org/pub/nfs-2.6.git
+	fetch = +refs/heads/*:refs/remotes/linux-nfs/*
 ...
 -------------------------------------------------
 
-- 
1.5.0.gb75812-dirty

[PATCH 3/6] user-manual: fix inconsistent use of pull and merge

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

I used "git pull ." instead of "git merge" here without any explanation.
Stick instead to "git merge" for now (the equivalent pull syntax is
still covered in a later chapter).

Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |   14 +++-----------
 1 files changed, 3 insertions(+), 11 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 8b5709b..f4ea967 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1133,17 +1133,9 @@ modified in two different ways in the remote branch and the local
 branch--then you are warned; the output may look something like this:
 
 -------------------------------------------------
-$ git pull . next
-Trying really trivial in-index merge...
-fatal: Merge requires file-level merging
-Nope.
-Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
-Merging:
-15e2162 world
-77976da goodbye
-found 1 common ancestor(s):
-d122ed4 initial
-Auto-merging file.txt
+$ git merge next
+ 100% (4/4) done
+Auto-merged file.txt
 CONFLICT (content): Merge conflict in file.txt
 Automatic merge failed; fix conflicts and then commit the result.
 -------------------------------------------------
-- 
1.5.0.gb75812-dirty

[PATCH 4/6] user-manual: fix missing colon in git-show example

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

There should be a colon in this git-show example.

Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index f4ea967..1e151b4 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1431,7 +1431,7 @@ modifying the working directory, you can do that with
 gitlink:git-show[1]:
 
 -------------------------------------------------
-$ git show HEAD^ path/to/file
+$ git show HEAD^:path/to/file
 -------------------------------------------------
 
 which will display the given version of the file.
-- 
1.5.0.gb75812-dirty

[PATCH 5/6] user-manual: fix rendering of history diagrams

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Asciidoc appears to interpret a backslash at the end of a line as
escaping the end-of-line character, which screws up the display of
history diagrams like

 o--o--o
	\
	 o--...

The obvious fix (replacing "\" by "\\") doesn't work.  The only
workaround I've found is to include all such diagrams in a LiteralBlock.
Asciidoc claims that should be equivalent to a literal paragraph, so I
don't understand why the difference--perhaps it's an asciidoc bug.

Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |   25 +++++++++++++++++++++----
 1 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1e151b4..0919574 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -437,11 +437,14 @@ We will sometimes represent git history using diagrams like the one
 below.  Commits are shown as "o", and the links between them with
 lines drawn with - / and \.  Time goes left to right:
 
+
+................................................
          o--o--o <-- Branch A
         /
  o--o--o <-- master
         \
          o--o--o <-- Branch B
+................................................
 
 If we need to talk about a particular commit, the character "o" may
 be replaced with another letter or number.
@@ -1928,25 +1931,29 @@ $ git commit
 You have performed no merges into mywork, so it is just a simple linear
 sequence of patches on top of "origin":
 
-
+................................................
  o--o--o <-- origin
         \
          o--o--o <-- mywork
+................................................
 
 Some more interesting work has been done in the upstream project, and
 "origin" has advanced:
 
+................................................
  o--o--O--o--o--o <-- origin
         \
          a--b--c <-- mywork
+................................................
 
 At this point, you could use "pull" to merge your changes back in;
 the result would create a new merge commit, like this:
 
-
+................................................
  o--o--O--o--o--o <-- origin
         \        \
          a--b--c--m <-- mywork
+................................................
  
 However, if you prefer to keep the history in mywork a simple series of
 commits without any merges, you may instead choose to use
@@ -1963,9 +1970,11 @@ point at the latest version of origin, then apply each of the saved
 patches to the new mywork.  The result will look like:
 
 
+................................................
  o--o--O--o--o--o <-- origin
 		 \
 		  a'--b'--c' <-- mywork
+................................................
 
 In the process, it may discover conflicts.  In that case it will stop
 and allow you to fix the conflicts; after fixing conflicts, use "git
@@ -2073,24 +2082,30 @@ The primary problem with rewriting the history of a branch has to do
 with merging.  Suppose somebody fetches your branch and merges it into
 their branch, with a result something like this:
 
+................................................
  o--o--O--o--o--o <-- origin
         \        \
          t--t--t--m <-- their branch:
+................................................
 
 Then suppose you modify the last three commits:
 
+................................................
 	 o--o--o <-- new head of origin
 	/
  o--o--O--o--o--o <-- old head of origin
+................................................
 
 If we examined all this history together in one repository, it will
 look like:
 
+................................................
 	 o--o--o <-- new head of origin
 	/
  o--o--O--o--o--o <-- old head of origin
         \        \
          t--t--t--m <-- their branch:
+................................................
 
 Git has no way of knowing that the new head is an updated version of
 the old head; it treats this situation exactly the same as it would if
@@ -2151,9 +2166,11 @@ commit.  Git calls this process a "fast forward".
 
 A fast forward looks something like this:
 
+................................................
  o--o--o--o <-- old head of the branch
            \
             o--o--o <-- new head of the branch
+................................................
 
 
 In some cases it is possible that the new head will *not* actually be
@@ -2161,11 +2178,11 @@ a descendant of the old head.  For example, the developer may have
 realized she made a serious mistake, and decided to backtrack,
 resulting in a situation like:
 
+................................................
  o--o--o--o--a--b <-- old head of the branch
            \
             o--o--o <-- new head of the branch
-
-
+................................................
 
 In this case, "git fetch" will fail, and print out a warning.
 
-- 
1.5.0.gb75812-dirty

[PATCH 6/6] user-manual: install user manual stylesheet with other web documents

[J. Bruce Fields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Install the stylesheet needed for the user manual.  This should solve
the problem of, e.g.,

	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

lacking a lot of formatting.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/install-webdoc.sh |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh
index b398193..cd3a18e 100755
--- a/Documentation/install-webdoc.sh
+++ b/Documentation/install-webdoc.sh
@@ -2,7 +2,7 @@
 
 T="$1"
 
-for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt
+for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css
 do
 	if test -f "$T/$h" &&
 	   diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
-- 
1.5.0.gb75812-dirty

Re: [PATCH 2/6] user-manual: fix inconsistent example

[J. Bruce Fields]

On Sat, Mar 10, 2007 at 11:35:27PM -0500, J. Bruce Fields wrote:
> From: J. Bruce Fields <bfields@citi.umich.edu>
> 
> The configuration file fragment here is inconsistent with the text
> above.  Thanks to Ramsay Jones for the correction.
> 
> Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>

Hm, I was hoping git-send-email would pick up Cc: lines from the commit
message in addition to Signed-off-by lines; oh well.  (Thanks for those
corrections, all were good.)

--b.

Re: [PATCH 2/6] user-manual: fix inconsistent example

[Ramsay Jones]

J. Bruce Fields wrote:
> On Sat, Mar 10, 2007 at 11:35:27PM -0500, J. Bruce Fields wrote:
>> From: J. Bruce Fields <bfields@citi.umich.edu>
>>
>> The configuration file fragment here is inconsistent with the text
>> above.  Thanks to Ramsay Jones for the correction.
>>
>> Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
> 
> Hm, I was hoping git-send-email would pick up Cc: lines from the commit
> message in addition to Signed-off-by lines; oh well.  (Thanks for those
> corrections, all were good.)
> 
> --b.
> 

Glad to be of help!

Did you figure out how to fix the diagram breakage?
(i.e. the "\<lf>" line continuation problem)

ATB,

Ramsay Jones

Re: [PATCH 2/6] user-manual: fix inconsistent example

[J. Bruce Fields]

On Tue, Mar 13, 2007 at 07:31:14PM +0000, Ramsay Jones wrote:
> J. Bruce Fields wrote:
> >On Sat, Mar 10, 2007 at 11:35:27PM -0500, J. Bruce Fields wrote:
> >>From: J. Bruce Fields <bfields@citi.umich.edu>
> >>
> >>The configuration file fragment here is inconsistent with the text
> >>above.  Thanks to Ramsay Jones for the correction.
> >>
> >>Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
> >
> >Hm, I was hoping git-send-email would pick up Cc: lines from the commit
> >message in addition to Signed-off-by lines; oh well.  (Thanks for those
> >corrections, all were good.)
> >
> >--b.
> >
> 
> Glad to be of help!
> 
> Did you figure out how to fix the diagram breakage?
> (i.e. the "\<lf>" line continuation problem)

I'm working around it by explicitly quoting those diagrams--see e.g.

http://git.kernel.org/?p=git/git.git;a=commit;h=1dc71a9155e209ed4da866eeb7c3064e4568532e

but I'm still trying to figure out exactly why it does that.

--b.

Re: Documentation (mostly user manual) patches

[Junio C Hamano]

"J. Bruce Fields" <bfields@citi.umich.edu> writes:

> OK, I hope I've understand what you're asking for: the following small
> (mainly user-manual) fixes all make sense for both 1.5.0 and 1.5.1, so
> (in addition to emailing them), I've applied them to the top of the
> "maint" branch at:
>
> 	git://linux-nfs.org/~bfields/git.git
>
> which is just a fork of your "maint".
>
> I haven't done anything to my "master", since I've got nothing
> 1.5.1-specific, and since I assume you'll take care of pulling this
> stuff into master some time later.

Thanks.  Will pull.

Re: Documentation (mostly user manual) patches

[Ramsay Jones]

J. Bruce Fields wrote:
> Sorry for the long silence.  You can also get these by pulling from
> 
> 	git://linux-nfs.org/~bfields/git.git
> 
> if you'd prefer.
> 
> --b.

I've just been reading the user manual (from the 1.5.0 tarball) for the
first time and noticed a few things which might need fixing up.
(Great work on the manual, BTW!)

Unfortunately, I don't have asciidoc or xmlto installed (I'm on Cygwin), so
I can't re-build the documentation to test any changes; and I don't know
how to use asciidoc markup anyway. ;-)

First, most history diagrams appear to be broken; this is due to the "\<lf>"
combination in the diagrams being interpreted as a line continuation! I don't
know what the asciidoc markup should be - \\ perhaps? The following indicates
that there are nine diagrams needing fixup:

    $ grep '\\$' Documentation/user-manual.txt | wc
          9      12     118
    $

In the "Fetching branches from other repositories" section, the content of the
configuration file displayed did not appear correct, given the text above.
In fact, both the url and fetch keys seem to be wrong; I'm assuming something
like the following was intended:

--->8---
@@ -596,8 +596,8 @@ a new stanza:
  $ cat .git/config
  ...
  [remote "linux-nfs"]
-        url = git://linux-nfs.org/~bfields/git.git
-	fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
+        url = git://linux-nfs.org/pub/nfs-2.6.git
+	fetch = +refs/heads/*:refs/remotes/linux-nfs/*
  ...
  -------------------------------------------------
---8<---

In chapter 4, "How to merge" section, a git pull invocation is demonstrated; I
suspect that a git merge was intended, thus:

--->8---
@@ -1128,7 +1128,7 @@ modified in two different ways in the remote branch and the local
  branch--then you are warned; the output may look something like this:

  -------------------------------------------------
-$ git pull . next
+$ git merge next
  Trying really trivial in-index merge...
  fatal: Merge requires file-level merging
  Nope.
---8<---

Having said that, does the command output need changing also?

In "Checking out an old version of a file", a git show invocation seems
to be missing a ":" between the <commit-ish> and the path, thus:

--->8---
@@ -1376,7 +1376,7 @@ modifying the working directory, you can do that with
  gitlink:git-show[1]:

  -------------------------------------------------
-$ git show HEAD^ path/to/file
+$ git show HEAD^:path/to/file
  -------------------------------------------------

  which will display the given version of the file.
---8<---

I haven't been following all the user-manual patches, so if you have already
fixed these up, sorry for the noise. ;-)

All the best,

Ramsay Jones