[PATCH] Random documentation fixes

The fixes focuses on improving the HTML output. Most noteworthy:

- Fix the Makefile to also make various *.html files depend on
included files.

- Consistently use 'NOTE: ...' instead of '[ ... ]' for additional
info.

- Fix ending '::' for description lists in OPTION section etc.

- Fix paragraphs in description lists ending up as preformated text.

- Always use listingblocks (preformatted text wrapped in lines with -----)
for examples that span empty lines, so they are put in only one HTML
block.

- Use '1.' instead of '(1)' for numbered lists.

- Fix linking to other GIT docs.

- git-rev-list.txt: put option descriptions in an OPTION section.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index aecae676dea995749ed9ba7122e31f5d0c64974c..bb21d6af44e6aa591c2adb33e0447853ac1c65c5 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -53,6 +53,9 @@ install: man
 $(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
        diff-format.txt diff-options.txt
 $(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
 $(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
        diff-format.txt diff-options.txt
 $(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt

+$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
+       diff-format.txt diff-options.txt
+$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt

 git.7: ../README
 
 clean:
 git.7: ../README
 
 clean:

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 390a72392b2aee91facd0c019474391ed64a646a..7c4dbef0086d1ca3c0a00cf5d093dd0d1c8622cd 100644 (file)
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -229,10 +229,10 @@ does rename or copy would not show in the output, and if the
 "o-file.c", it would find the commit that changed the statement
 when it was in "o-file.c".
 
 "o-file.c", it would find the commit that changed the statement
 when it was in "o-file.c".
 

-[ BTW, the current versions of "git-diff-tree -C" is not eager
+NOTE: The current versions of "git-diff-tree -C" is not eager

   enough to find copies, and it will miss the fact that a-file.c
   was created by copying o-file.c unless o-file.c was somehow
   enough to find copies, and it will miss the fact that a-file.c
   was created by copying o-file.c unless o-file.c was somehow

-  changed in the same commit.]
+  changed in the same commit.

 
 You can use the --pickaxe-all flag in addition to the -S flag.
 This causes the differences from all the files contained in
 
 You can use the --pickaxe-all flag in addition to the -S flag.
 This causes the differences from all the files contained in


@@ -243,6 +243,6 @@ that contain this changed "if" statement:
                nitfol();
        }' --pickaxe-all
 
                nitfol();
        }' --pickaxe-all
 

-[ Side note.  This option is called "--pickaxe-all" because -S
+NOTE: This option is called "--pickaxe-all" because -S

   option is internally called "pickaxe", a tool for software
   option is internally called "pickaxe", a tool for software

-  archaeologists.]
+  archaeologists.

diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt
index 1908b92f3804c9d0e5951ee8050c1de312fb30a4..a1f03df8f1cda96e13586fc9d447dfc8e5ffcf07 100644 (file)
--- a/Documentation/diffcore.txt
+++ b/Documentation/diffcore.txt
@@ -254,11 +254,11 @@ As an example, typical orderfile for the core GIT probably
 would look like this:
 
 ------------------------------------------------
 would look like this:
 
 ------------------------------------------------

-    README
-    Makefile
-    Documentation
-    *.h
-    *.c
-    t
+README
+Makefile
+Documentation
+*.h
+*.c
+t

 ------------------------------------------------
 
 ------------------------------------------------
 

diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt
index 4046360217f3f4f7db9b41deab0c06773473d431..5b9037de9f90626d9715de49e39f9708fdc25c75 100644 (file)
--- a/Documentation/git-applypatch.txt
+++ b/Documentation/git-applypatch.txt
@@ -30,7 +30,7 @@ OPTIONS
 <patch>::
        The patch to apply.
 
 <patch>::
        The patch to apply.
 

-<info>:
+<info>::

        Author and subject information extracted from e-mail,
        used on "author" line and as the first line of the
        commit log message.
        Author and subject information extracted from e-mail,
        used on "author" line and as the first line of the
        commit log message.

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index b124b0751c195db82a49d0bcf434da429ec71019..ede06dac36f798b85d26b467a3a7953fca244f6a 100644 (file)
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -91,7 +91,7 @@ Author
 Written by Linus Torvalds <torvalds@osdl.org>
 
 Documentation
 Written by Linus Torvalds <torvalds@osdl.org>
 
 Documentation

---------------
+-------------

 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index e6a8c878538acd32061546dac365634cdd532a89..cd5b97d62cd42205044d90cd5f44ebe4f82a2b5d 100644 (file)
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -38,9 +38,9 @@ OPTIONS
        option is used, your working tree does not have to match
        the HEAD commit.  The cherry-pick is done against the
        beginning state of your working tree.
        option is used, your working tree does not have to match
        the HEAD commit.  The cherry-pick is done against the
        beginning state of your working tree.

-
-       This is useful when cherry-picking more than one commits'
-       effect to your working tree in a row.
++
+This is useful when cherry-picking more than one commits'
+effect to your working tree in a row.

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 705be4e3346f61f1c7b061f8efd6dc907f769a4a..895f7336487696254c1e34611226f725ae58bd87 100644 (file)
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -58,11 +58,11 @@ following environment variables.
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
 
        GIT_COMMITTER_NAME
        GIT_COMMITTER_EMAIL
 

-(nb <,> and '\n's are stripped)
+(nb "<", ">" and "\n"s are stripped)

 
 A commit comment is read from stdin (max 999 chars). If a changelog
 
 A commit comment is read from stdin (max 999 chars). If a changelog

-entry is not provided via '<' redirection, "git-commit-tree" will just wait
-for one to be entered and terminated with ^D
+entry is not provided via "<" redirection, "git-commit-tree" will just wait
+for one to be entered and terminated with ^D.

 
 Diagnostics
 -----------
 
 Diagnostics
 -----------

diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index cd01994877240fdc725aab7050d0634e7a15db2e..b5753a46dc4bdf8fc426acd32f3add9f95887a50 100644 (file)
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -51,15 +51,15 @@ OPTIONS
        The 'HEAD' branch from CVS is imported to the 'origin' branch within
        the git repository, as 'HEAD' already has a special meaning for git.
        Use this option if you want to import into a different branch.
        The 'HEAD' branch from CVS is imported to the 'origin' branch within
        the git repository, as 'HEAD' already has a special meaning for git.
        Use this option if you want to import into a different branch.

-
-       Use '-o master' for continuing an import that was initially done by
-       the old cvs2git tool.
++
+Use '-o master' for continuing an import that was initially done by
+the old cvs2git tool.

 
 -p <options-for-cvsps>::
        Additional options for cvsps.
        The options '-u' and '-A' are implicit and should not be used here.
 
 -p <options-for-cvsps>::
        Additional options for cvsps.
        The options '-u' and '-A' are implicit and should not be used here.

-
-       If you need to pass multiple options, separate them with a comma.
++
+If you need to pass multiple options, separate them with a comma.

 
 -m::    
        Attempt to detect merges based on the commit message. This option
 
 -m::    
        Attempt to detect merges based on the commit message. This option

diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 56ed673edaa8f484e3a88272f74aac0121667b3e..8b6a953c03aa7971f8f7e6e7b7573c4b0fa64007 100644 (file)
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -86,8 +86,8 @@ the more useful of the two in that what it does can't be emulated with
 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
 The non-cached version asks the question:
 
 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
 The non-cached version asks the question:
 

-   show me the differences between HEAD and the currently checked out
-   tree - index contents _and_ files that aren't up-to-date
+  show me the differences between HEAD and the currently checked out
+  tree - index contents _and_ files that aren't up-to-date

 
 which is obviously a very useful question too, since that tells you what
 you *could* commit. Again, the output matches the "git-diff-tree -r"
 
 which is obviously a very useful question too, since that tells you what
 you *could* commit. Again, the output matches the "git-diff-tree -r"


@@ -107,13 +107,13 @@ not up-to-date and may contain new stuff. The all-zero sha1 means that to
 get the real diff, you need to look at the object in the working directory
 directly rather than do an object-to-object diff.
 
 get the real diff, you need to look at the object in the working directory
 directly rather than do an object-to-object diff.
 

-NOTE! As with other commands of this type, "git-diff-index" does not
+NOTE: As with other commands of this type, "git-diff-index" does not

 actually look at the contents of the file at all. So maybe
 `kernel/sched.c` hasn't actually changed, and it's just that you
 touched it. In either case, it's a note that you need to
 "git-upate-cache" it to make the cache be in sync.
 
 actually look at the contents of the file at all. So maybe
 `kernel/sched.c` hasn't actually changed, and it's just that you
 touched it. In either case, it's a note that you need to
 "git-upate-cache" it to make the cache be in sync.
 

-NOTE 2! You can have a mixture of files show up as "has been updated"
+NOTE: You can have a mixture of files show up as "has been updated"

 and "is still dirty in the working directory" together. You can always
 tell which file is in which state, since the "has been updated" ones
 show a valid sha1, and the "not in sync with the index" ones will
 and "is still dirty in the working directory" together. You can always
 tell which file is in which state, since the "has been updated" ones
 show a valid sha1, and the "not in sync with the index" ones will

diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 7f18bbfc60973bfe38305bcfc034d7caf0123abd..339a92287abd10be3b592c2fcb32788470f9f867 100644 (file)
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -101,16 +101,18 @@ An example of normal usage is:
 which tells you that the last commit changed just one file (it's from
 this one:
 
 which tells you that the last commit changed just one file (it's from
 this one:
 

-  commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
-  tree 5319e4d609cdd282069cc4dce33c1db559539b03
-  parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
-  author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
-  committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
-
-  Make "git-fsck-objects" print out all the root commits it finds.
-
-  Once I do the reference tracking, I'll also make it print out all the
-  HEAD commits it finds, which is even more interesting.
+-----------------------------------------------------------------------------
+commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
+tree 5319e4d609cdd282069cc4dce33c1db559539b03
+parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
+author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+
+Make "git-fsck-objects" print out all the root commits it finds.
+
+Once I do the reference tracking, I'll also make it print out all the
+HEAD commits it finds, which is even more interesting.
+-----------------------------------------------------------------------------

 
 in case you care).
 
 
 in case you care).
 

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 09065100029b9055197793addce76834ad8f5ed7..1fa9f4dbf4198e35f49e299f772c054f50251b63 100644 (file)
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -39,7 +39,7 @@ Written by Linus Torvalds <torvalds@osdl.org> and
 Junio C Hamano <junkio@cox.net>
 
 Documentation
 Junio C Hamano <junkio@cox.net>
 
 Documentation

---------------
+-------------

 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT

diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt
index 715defd2f69f71af5a3b0665b5e0888bf76efa84..ba251a5152e8b7d3bd2de508a02f3b7c5170949d 100644 (file)
--- a/Documentation/git-fsck-objects.txt
+++ b/Documentation/git-fsck-objects.txt
@@ -19,9 +19,9 @@ OPTIONS
 -------
 <object>::
        An object to treat as the head of an unreachability trace.
 -------
 <object>::
        An object to treat as the head of an unreachability trace.

-
-       If no objects are given, git-fsck-objects defaults to using the
-       index file and all SHA1 references in .git/refs/* as heads.
++
+If no objects are given, git-fsck-objects defaults to using the
+index file and all SHA1 references in .git/refs/* as heads.

 
 --unreachable::
        Print out objects that exist but that aren't readable from any
 
 --unreachable::
        Print out objects that exist but that aren't readable from any


@@ -128,7 +128,7 @@ GIT_OBJECT_DIRECTORY::
 GIT_INDEX_FILE::
        used to specify the index file of the cache
 
 GIT_INDEX_FILE::
        used to specify the index file of the cache
 

-GIT_ALTERNATE_OBJECT_DIRECTORIES:
+GIT_ALTERNATE_OBJECT_DIRECTORIES::

        used to specify additional object database roots (usually unset)
 
 Author
        used to specify additional object database roots (usually unset)
 
 Author

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 87cc362ad88a4e65e7216d7db78b3219ddf65df8..940285f8c8caf52f06ac2fb0008026a1425b24eb 100644 (file)
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -70,11 +70,11 @@ OPTIONS
 -t::
        Identify the file status with the following tags (followed by
        a space) at the start of each line:
 -t::
        Identify the file status with the following tags (followed by
        a space) at the start of each line:

-       H       cached
-       M       unmerged
-       R       removed/deleted
-       C       modifed/changed
-       K       to be killed
+       H::     cached
+       M::     unmerged
+       R::     removed/deleted
+       C::     modifed/changed
+       K::     to be killed

        ?       other
 
 --::
        ?       other
 
 --::


@@ -110,13 +110,13 @@ flags --others or --ignored are specified.
 
 These exclude patterns come from these places:
 
 
 These exclude patterns come from these places:
 

- (1) command line flag --exclude=<pattern> specifies a single
+  1. command line flag --exclude=<pattern> specifies a single

      pattern.
 
      pattern.
 

- (2) command line flag --exclude-from=<file> specifies a list of
+  2. command line flag --exclude-from=<file> specifies a list of

      patterns stored in a file.
 
      patterns stored in a file.
 

- (3) command line flag --exclude-per-directory=<name> specifies
+  3. command line flag --exclude-per-directory=<name> specifies

      a name of the file in each directory 'git-ls-files'
      examines, and if exists, its contents are used as an
      additional list of patterns.
      a name of the file in each directory 'git-ls-files'
      examines, and if exists, its contents are used as an
      additional list of patterns.


@@ -168,12 +168,13 @@ An exclude pattern is of the following format:
  - otherwise, it is a shell glob pattern, suitable for
    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
    slash in the pattern must match a slash in the pathname.
  - otherwise, it is a shell glob pattern, suitable for
    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
    slash in the pattern must match a slash in the pathname.

-   "Documentation/*.html" matches "Documentation/git.html" but
+   "Documentation/\*.html" matches "Documentation/git.html" but

    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
    "cat-file.c" but not "mozilla-sha1/sha1.c".
 
 An example:
 
    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
    "cat-file.c" but not "mozilla-sha1/sha1.c".
 
 An example:
 

+--------------------------------------------------------------

     $ cat .git/ignore
     # ignore objects and archives, anywhere in the tree.
     *.[oa]
     $ cat .git/ignore
     # ignore objects and archives, anywhere in the tree.
     *.[oa]


@@ -186,6 +187,7 @@ An example:
         --exclude='Documentation/*.[0-9]' \
         --exclude-from=.git/ignore \
         --exclude-per-directory=.gitignore
         --exclude='Documentation/*.[0-9]' \
         --exclude-from=.git/ignore \
         --exclude-per-directory=.gitignore

+--------------------------------------------------------------

 
 
 See Also
 
 
 See Also

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 970150a128a08c7da14c1ee56b8e9f8394cb3c25..44aba940d7f0da88c2760633fe2cad8f415e1f31 100644 (file)
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -76,7 +76,8 @@ Documentation by Junio C Hamano
 
 See-Also
 --------
 
 See-Also
 --------

-git-repack(1) git-prune-packed(1)
+gitlink:git-repack[1]
+gitlink:git-prune-packed[1]

 
 GIT
 ---
 
 GIT
 ---

diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 0cb19b00586231a6cc108b09177c405a1ba5c5d9..5c48a0937ac7aa1a41a585646e40fd03302e1b5d 100644 (file)
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -34,7 +34,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
 
 See-Also
 --------
 
 See-Also
 --------

-git-pack-objects(1) git-repack(1)
+gitlink:git-pack-objects[1]
+gitlink:git-repack[1]

 
 GIT
 ---
 
 GIT
 ---

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 0639bd04b2915c1e381021ef2018b203adc13b4b..5653baccaffe888bc5a238e0fef8212045ab187d 100644 (file)
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -84,10 +84,10 @@ fast forward situation).
 When two trees are specified, the user is telling git-read-tree
 the following:
 
 When two trees are specified, the user is telling git-read-tree
 the following:
 

-    (1) The current index and work tree is derived from $H, but
+     1. The current index and work tree is derived from $H, but

         the user may have local changes in them since $H;
 
         the user may have local changes in them since $H;
 

-    (2) The user wants to fast-forward to $M.
+     2. The user wants to fast-forward to $M.

 
 In this case, the "git-read-tree -m $H $M" command makes sure
 that no local change is lost as the result of this "merge".
 
 In this case, the "git-read-tree -m $H $M" command makes sure
 that no local change is lost as the result of this "merge".

diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 2e95e111f36612259f32f45392cd466fa9c4bf79..bd830ada274335b723f3382b9b4a554fa3c15701 100644 (file)
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -51,7 +51,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
 
 See-Also
 --------
 
 See-Also
 --------

-git-pack-objects(1) git-prune-packed(1)
+gitlink:git-pack-objects[1]
+gitlink:git-prune-packed[1]

 
 GIT
 ---
 
 GIT
 ---

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 02ee93ee4191e60861ccd3353b639d08de0f3567..f386a3a79bd1752b051de7c1e07d549bfa432de7 100644 (file)
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -22,65 +22,69 @@ that point. Their parents are implied. "git-rev-list foo bar ^baz" thus
 means "list all the commits which are included in 'foo' and 'bar', but
 not in 'baz'".
 
 means "list all the commits which are included in 'foo' and 'bar', but
 not in 'baz'".
 

-If *--pretty* is specified, print the contents of the commit changesets
-in human-readable form.
-
-The *--objects* flag causes 'git-rev-list' to print the object IDs of
-any object referenced by the listed commits. 'git-rev-list --objects foo
-^bar' thus means "send me all object IDs which I need to download if
-I have the commit object 'bar', but not 'foo'".
-
-The *--bisect* flag limits output to the one commit object which is
-roughly halfway between the included and excluded commits. Thus,
-if 'git-rev-list --bisect foo ^bar
-^baz' outputs 'midpoint', the output
-of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
-^bar
-^baz'
-would be of roughly the same length. Finding the change which introduces
-a regression is thus reduced to a binary search: repeatedly generate and
-test new 'midpoint's until the commit chain is of length one.
-
-If *--merge-order* is specified, the commit history is decomposed into a
-unique sequence of minimal, non-linear epochs and maximal, linear epochs.
-Non-linear epochs are then linearised by sorting them into merge order, which
-is described below.
-
+OPTIONS
+-------
+--pretty::
+       Print the contents of the commit changesets in human-readable form.
+
+--objects::
+       Print the object IDs of any object referenced by the listed commits.
+       'git-rev-list --objects foo ^bar' thus means "send me all object IDs
+       which I need to download if I have the commit object 'bar', but
+       not 'foo'".
+
+--bisect::
+       Limit output to the one commit object which is roughly halfway
+       between the included and excluded commits. Thus, if 'git-rev-list
+       --bisect foo ^bar ^baz' outputs 'midpoint', the output
+       of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint
+       ^bar ^baz' would be of roughly the same length. Finding the change
+       which introduces a regression is thus reduced to a binary search:
+       repeatedly generate and test new 'midpoint's until the commit chain
+       is of length one.
+
+--merge-order::
+       When specified the commit history is decomposed into a unique
+       sequence of minimal, non-linear epochs and maximal, linear epochs.
+       Non-linear epochs are then linearised by sorting them into merge
+       order, which is described below.
++

 Maximal, linear epochs correspond to periods of sequential development.
 Minimal, non-linear epochs correspond to periods of divergent development
 followed by a converging merge. The theory of epochs is described in more
 detail at
 link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].
 Maximal, linear epochs correspond to periods of sequential development.
 Minimal, non-linear epochs correspond to periods of divergent development
 followed by a converging merge. The theory of epochs is described in more
 detail at
 link:http://blackcubes.dyndns.org/epoch/[http://blackcubes.dyndns.org/epoch/].

-
++

 The merge order for a non-linear epoch is defined as a linearisation for which
 the following invariants are true:
 The merge order for a non-linear epoch is defined as a linearisation for which
 the following invariants are true:

-
++

     1. if a commit P is reachable from commit N, commit P sorts after commit N
        in the linearised list.
     2. if Pi and Pj are any two parents of a merge M (with i < j), then any
        commit N, such that N is reachable from Pj but not reachable from Pi,
        sorts before all commits reachable from Pi.
     1. if a commit P is reachable from commit N, commit P sorts after commit N
        in the linearised list.
     2. if Pi and Pj are any two parents of a merge M (with i < j), then any
        commit N, such that N is reachable from Pj but not reachable from Pi,
        sorts before all commits reachable from Pi.

-
++

 Invariant 1 states that later commits appear before earlier commits they are
 derived from.
 Invariant 1 states that later commits appear before earlier commits they are
 derived from.

-
++

 Invariant 2 states that commits unique to "later" parents in a merge, appear
 before all commits from "earlier" parents of a merge.
 
 Invariant 2 states that commits unique to "later" parents in a merge, appear
 before all commits from "earlier" parents of a merge.
 

-If *--show-breaks* is specified, each item of the list is output with a
-2-character prefix consisting of one of: (|), (^), (=) followed by a space.
-
+--show-breaks::
+       Each item of the list is output with a 2-character prefix consisting
+       of one of: (|), (^), (=) followed by a space.
++

 Commits marked with (=) represent the boundaries of minimal, non-linear epochs
 and correspond either to the start of a period of divergent development or to
 the end of such a period.
 Commits marked with (=) represent the boundaries of minimal, non-linear epochs
 and correspond either to the start of a period of divergent development or to
 the end of such a period.

-
++

 Commits marked with (|) are direct parents of commits immediately preceding
 the marked commit in the list.
 Commits marked with (|) are direct parents of commits immediately preceding
 the marked commit in the list.

-
++

 Commits marked with (^) are not parents of the immediately preceding commit.
 These "breaks" represent necessary discontinuities implied by trying to
 represent an arbtirary DAG in a linear form.
 Commits marked with (^) are not parents of the immediately preceding commit.
 These "breaks" represent necessary discontinuities implied by trying to
 represent an arbtirary DAG in a linear form.

-
++

 *--show-breaks* is only valid if *--merge-order* is also specified.
 
 Author
 *--show-breaks* is only valid if *--merge-order* is also specified.
 
 Author

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 47476586d91af397930eb94838972c960e3e77cf..feebd81da5889da2e77dc8508f8b7e3d642e6214 100644 (file)
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -29,9 +29,9 @@ OPTIONS
        working tree does not have to match the HEAD commit.
        The revert is done against the beginning state of your
        working tree.
        working tree does not have to match the HEAD commit.
        The revert is done against the beginning state of your
        working tree.

-
-       This is useful when reverting more than one commits'
-       effect to your working tree in a row.
++
+This is useful when reverting more than one commits'
+effect to your working tree in a row.

 
 
 Author
 
 
 Author

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index a2763bd74fbad3a79b09588312127a1b98911a56..b95e33db528ce76ae495147b034df9adeaac1273 100644 (file)
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -21,35 +21,37 @@ The header of the email is configurable by command line options.  If not
 specified on the command line, the user will be prompted with a ReadLine
 enabled interface to provide the necessary information.
 
 specified on the command line, the user will be prompted with a ReadLine
 enabled interface to provide the necessary information.
 

+OPTIONS
+-------

 The options available are:
 
 The options available are:
 

-  --to
+--to::

        Specify the primary recipient of the emails generated.
        Generally, this will be the upstream maintainer of the
        project involved.
 
        Specify the primary recipient of the emails generated.
        Generally, this will be the upstream maintainer of the
        project involved.
 

-   --from
+--from::

        Specify the sender of the emails.  This will default to
        the value GIT_COMMITTER_IDENT, as returned by "git-var -l".
        The user will still be prompted to confirm this entry.
 
        Specify the sender of the emails.  This will default to
        the value GIT_COMMITTER_IDENT, as returned by "git-var -l".
        The user will still be prompted to confirm this entry.
 

-   --compose
+--compose::

        Use \$EDITOR to edit an introductory message for the
        patch series.
 
        Use \$EDITOR to edit an introductory message for the
        patch series.
 

-   --subject
+--subject::

        Specify the initial subject of the email thread.
        Only necessary if --compose is also set.  If --compose
        is not set, this will be prompted for.
 
        Specify the initial subject of the email thread.
        Only necessary if --compose is also set.  If --compose
        is not set, this will be prompted for.
 

-   --in-reply-to
+--in-reply-to::

        Specify the contents of the first In-Reply-To header.
        Subsequent emails will refer to the previous email 
        instead of this if --chain-reply-to is set (the default)
        Only necessary if --compose is also set.  If --compose
        is not set, this will be prompted for.
 
        Specify the contents of the first In-Reply-To header.
        Subsequent emails will refer to the previous email 
        instead of this if --chain-reply-to is set (the default)
        Only necessary if --compose is also set.  If --compose
        is not set, this will be prompted for.
 

-   --chain-reply-to, --no-chain-reply-to
+--chain-reply-to, --no-chain-reply-to::

        If this is set, each email will be sent as a reply to the previous
        email sent.  If disabled with "--no-chain-reply-to", all emails after
        the first will be sent as replies to the first email sent.  When using
        If this is set, each email will be sent as a reply to the previous
        email sent.  If disabled with "--no-chain-reply-to", all emails after
        the first will be sent as replies to the first email sent.  When using


@@ -57,7 +59,7 @@ The options available are:
        entire patch series.
        Default is --chain-reply-to
 
        entire patch series.
        Default is --chain-reply-to
 

-   --smtp-server
+--smtp-server::

        If set, specifies the outgoing SMTP server to use.  Defaults to
        localhost.
 
        If set, specifies the outgoing SMTP server to use.  Defaults to
        localhost.
 

diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 1837fb79c7b26e0f25e2ec685de31005726996be..219dfc2ef6541216f2c46329e3e82664232b4b35 100644 (file)
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -61,9 +61,9 @@ this flag.
 Without '--all' and without any '<ref>', the refs that exist
 both on the local side and on the remote side are updated.
 
 Without '--all' and without any '<ref>', the refs that exist
 both on the local side and on the remote side are updated.
 

-When '<ref>'s are specified explicitly, it can be either a
+When one or more '<ref>' are specified explicitly, it can be either a

 single pattern, or a pair of such pattern separated by a colon
 single pattern, or a pair of such pattern separated by a colon

-':' (this means that a ref name cannot have a colon in it).  A
+":" (this means that a ref name cannot have a colon in it).  A

 single pattern '<name>' is just a shorthand for '<name>:<name>'.
 
 Each pattern pair consists of the source side (before the colon)
 single pattern '<name>' is just a shorthand for '<name>:<name>'.
 
 Each pattern pair consists of the source side (before the colon)


@@ -79,10 +79,10 @@ destination side.
 
  - If <dst> does not match any remote ref, either
 
 
  - If <dst> does not match any remote ref, either
 

-   - it has to start with "refs/"; <dst> is used as the
+   * it has to start with "refs/"; <dst> is used as the

      destination literally in this case.
 
      destination literally in this case.
 

-   - <src> == <dst> and the ref that matched the <src> must not
+   * <src> == <dst> and the ref that matched the <src> must not

      exist in the set of remote refs; the ref matched <src>
      locally is used as the name of the destination.
 
      exist in the set of remote refs; the ref matched <src>
      locally is used as the name of the destination.
 

diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index a02a2b051c1463604f69d9f06c8825f8e720ab34..6ef59acf50a14088d0f93b5ac745366159f751f6 100644 (file)
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -14,11 +14,12 @@ DESCRIPTION
 
 Sets up the normal git environment variables and a few helper functions
 (currently just "die()"), and returns ok if it all looks like a git archive.
 
 Sets up the normal git environment variables and a few helper functions
 (currently just "die()"), and returns ok if it all looks like a git archive.

-So use it something like
+So, to make the rest of the git scripts more careful and readable,
+use it as follows:

 
 

-       . git-sh-setup || die "Not a git archive"
-
-to make the rest of the git scripts more careful and readable.
+-------------------------------------------------
+. git-sh-setup || die "Not a git archive"
+-------------------------------------------------

 
 Author
 ------
 
 Author
 ------

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 0d9847c5287dec916e314ac2a652e7f9c55992d0..6fa1d980f6144a51b7adc865baa6b1dbf5e753d0 100644 (file)
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -101,7 +101,7 @@ Using --cacheinfo or --info-only
 current working directory.  This is useful for minimum-checkout
 merging.
 
 current working directory.  This is useful for minimum-checkout
 merging.
 

-  To pretend you have a file with mode and sha1 at path, say:
+To pretend you have a file with mode and sha1 at path, say:

 
    $ git-update-index --cacheinfo mode sha1 path
 
 
    $ git-update-index --cacheinfo mode sha1 path
 

diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt
index 31f80a8b30b29078aeea29bfb52849a056de75ec..c1c71720889b7b9aadf093870f82289ae4bd9d51 100644 (file)
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.txt
@@ -15,21 +15,23 @@ DESCRIPTION
 -----------
 Prints a git logical variable.
 
 -----------
 Prints a git logical variable.
 

--l causes the logical variables to be listed.
+OPTIONS
+-------
+-l::
+       Cause the logical variables to be listed.

 
 EXAMPLE
 --------
 
 EXAMPLE
 --------

-$git-var GIT_AUTHOR_IDENT
-
-Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600
+       $ git-var GIT_AUTHOR_IDENT
+       Eric W. Biederman <ebiederm@lnxi.com> 1121223278 -0600

 
 
 VARIABLES
 ----------
 
 
 VARIABLES
 ----------

-GIT_AUTHOR_IDENT
+GIT_AUTHOR_IDENT::

     The author of a piece of code.
 
     The author of a piece of code.
 

-GIT_COMMITTER_IDENT
+GIT_COMMITTER_IDENT::

     The person who put a piece of code into git.
 
 Diagnostics
     The person who put a piece of code into git.
 
 Diagnostics

diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index a99172ca1edc75df35d10a1ed4eacc8cea02da06..b100aa765a2de023a4c18b1ef9643a03b98243c4 100644 (file)
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -25,15 +25,19 @@ OPTIONS
 
 -v::
        After verifying the pack, show list of objects contained
 
 -v::
        After verifying the pack, show list of objects contained

-       in the pack.  The format used is:
+       in the pack.

 
 

-               SHA1 type size offset-in-packfile
+OUTPUT FORMAT
+-------------
+When specifying the -v option the format used is:

 
 

-       for objects that are not deltified in the pack, and
+       SHA1 type size offset-in-packfile

 
 

-               SHA1 type size offset-in-packfile depth base-SHA1
+for objects that are not deltified in the pack, and

 
 

-       for objects that are deltified.
+       SHA1 type size offset-in-packfile depth base-SHA1
+
+for objects that are deltified.

 
 Author
 ------
 
 Author
 ------

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 8642182c89109b50eecc741cc71dde90f27d9048..8dbddbf63fc92c1ae85b2bdbda3266b92d67407d 100644 (file)
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -2,84 +2,78 @@
        The "remote" repository to pull from.  One of the
        following notations can be used to name the repository
        to pull from:
        The "remote" repository to pull from.  One of the
        following notations can be used to name the repository
        to pull from:

-
-               Rsync URL
-                       rsync://remote.machine/path/to/repo.git/
-
-               HTTP(s) URL
-                       http://remote.machine/path/to/repo.git/
-
-               GIT URL
-                       git://remote.machine/path/to/repo.git/
-                       remote.machine:/path/to/repo.git/
-
-               Local directory
-                       /path/to/repo.git/
-
-       In addition to the above, as a short-hand, the name of a
-       file in $GIT_DIR/remotes directory can be given; the
-       named file should be in the following format:
-
-               URL: one of the above URL format
-               Push: <refspec>...
-               Pull: <refspec>...
-
-       When such a short-hand is specified in place of
-       <repository> without <refspec> parameters on the command
-       line, <refspec>... specified on Push lines or Pull lines
-       are used for "git push" and "git fetch/pull",
-       respectively.
-
-       The name of a file in $GIT_DIR/branches directory can be
-       specified as an older notation short-hand; the named
-       file should contain a single line, a URL in one of the
-       above formats, optionally followed by a hash '#' and the
-       name of remote head (URL fragment notation).
-       $GIT_DIR/branches/<remote> file that stores a <url>
-       without the fragment is equivalent to have this in the
-       corresponding file in the $GIT_DIR/remotes/ directory
-
-               URL: <url>
-               Pull: refs/heads/master:<remote>
-
-       while having <url>#<head> is equivalent to
-
-               URL: <url>
-               Pull: refs/heads/<head>:<remote>
++
+===============================================================
+- Rsync URL:           rsync://remote.machine/path/to/repo.git/
+- HTTP(s) URL:         http://remote.machine/path/to/repo.git/
+- GIT URL:             git://remote.machine/path/to/repo.git/
+                       or remote.machine:/path/to/repo.git/
+- Local directory:     /path/to/repo.git/
+===============================================================
++
+In addition to the above, as a short-hand, the name of a
+file in $GIT_DIR/remotes directory can be given; the
+named file should be in the following format:
++
+       URL: one of the above URL format
+       Push: <refspec>...
+       Pull: <refspec>...
++
+When such a short-hand is specified in place of
+<repository> without <refspec> parameters on the command
+line, <refspec>... specified on Push lines or Pull lines
+are used for "git push" and "git fetch/pull",
+respectively.
++
+The name of a file in $GIT_DIR/branches directory can be
+specified as an older notation short-hand; the named
+file should contain a single line, a URL in one of the
+above formats, optionally followed by a hash '#' and the
+name of remote head (URL fragment notation).
+$GIT_DIR/branches/<remote> file that stores a <url>
+without the fragment is equivalent to have this in the
+corresponding file in the $GIT_DIR/remotes/ directory
++
+       URL: <url>
+       Pull: refs/heads/master:<remote>
++
+while having <url>#<head> is equivalent to
++
+       URL: <url>
+       Pull: refs/heads/<head>:<remote>

 
 <refspec>::
        The canonical format of a <refspec> parameter is
        '+?<src>:<dst>'; that is, an optional plus '+', followed
        by the source ref, followed by a colon ':', followed by
        the destination ref.
 
 <refspec>::
        The canonical format of a <refspec> parameter is
        '+?<src>:<dst>'; that is, an optional plus '+', followed
        by the source ref, followed by a colon ':', followed by
        the destination ref.

-
-       When used in "git push", the <src> side can be an
-       arbitrary "SHA1 expression" that can be used as an
-       argument to "git-cat-file -t".  E.g. "master~4" (push
-       four parents before the current master head).
-
-        For "git push", the local ref that matches <src> is used
-        to fast forward the remote ref that matches <dst>.  If
-        the optional plus '+' is used, the remote ref is updated
-        even if it does not result in a fast forward update.
-
-       For "git fetch/pull", the remote ref that matches <src>
-       is fetched, and if <dst> is not empty string, the local
-       ref that matches it is fast forwarded using <src>.
-       Again, if the optional plus '+' is used, the local ref
-       is updated even if it does not result in a fast forward
-       update.
-
-       Some short-cut notations are also supported.
-
-       * For backward compatibility, "tag" is almost ignored;
-          it just makes the following parameter <tag> to mean a
-          refspec "refs/tags/<tag>:refs/tags/<tag>".
-
-        * A parameter <ref> without a colon is equivalent to
-          <ref>: when pulling/fetching, and <ref>:<ref> when
-          pushing.  That is, do not store it locally if
-          fetching, and update the same name if pushing.
++
+When used in "git push", the <src> side can be an
+arbitrary "SHA1 expression" that can be used as an
+argument to "git-cat-file -t".  E.g. "master~4" (push
+four parents before the current master head).
++
+For "git push", the local ref that matches <src> is used
+to fast forward the remote ref that matches <dst>.  If
+the optional plus '+' is used, the remote ref is updated
+even if it does not result in a fast forward update.
++
+For "git fetch/pull", the remote ref that matches <src>
+is fetched, and if <dst> is not empty string, the local
+ref that matches it is fast forwarded using <src>.
+Again, if the optional plus '+' is used, the local ref
+is updated even if it does not result in a fast forward
+update.
++
+Some short-cut notations are also supported.
++
+* For backward compatibility, "tag" is almost ignored;
+  it just makes the following parameter <tag> to mean a
+  refspec "refs/tags/<tag>:refs/tags/<tag>".
+* A parameter <ref> without a colon is equivalent to
+  <ref>: when pulling/fetching, and <ref>:<ref> when
+  pushing.  That is, do not store it locally if
+  fetching, and update the same name if pushing.

 
 -a, \--append::
        Append ref names and object names of fetched refs to the
 
 -a, \--append::
        Append ref names and object names of fetched refs to the