Autogenerated HTML docs for v1.5.6.1-93-gef98

diff --git a/gitcli.html b/gitcli.html
index 5603bd1f89d63a242a765c4a6dffd6b9565dc4f9..7eca88442302f8183fb9465f078c408e1e9558c3 100644 (file)
--- a/gitcli.html
+++ b/gitcli.html
@@ -276,8 +276,45 @@ gitcli(7) Manual Page
 </div>\r
 <h2>DESCRIPTION</h2>\r
 <div class="sectionbody">\r
-<p>This manual describes best practice in how to use git CLI.  Here are\r
-the rules that you should follow when you are scripting git:</p>\r
+<p>This manual describes the convention used throughout git CLI.</p>\r
+<p>Many commands take revisions (most often "commits", but sometimes\r
+"tree-ish", depending on the context and command) and paths as their\r
+arguments.  Here are the rules:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+Revisions come first and then paths.\r
+   E.g. in <tt>git diff v1.0 v2.0 arch/x86 include/asm-x86</tt>,\r
+   <tt>v1.0</tt> and <tt>v2.0</tt> are revisions and <tt>arch/x86</tt> and <tt>include/asm-x86</tt>\r
+   are paths.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+When an argument can be misunderstood as either a revision or a path,\r
+   they can be disambiguated by placing <tt>--</tt> between them.\r
+   E.g. <tt>git diff -- HEAD</tt> is, "I have a file called HEAD in my work\r
+   tree.  Please show changes between the version I staged in the index\r
+   and what I have in the work tree for that file". not "show difference\r
+   between the HEAD commit and the work tree as a whole".  You can say\r
+   <tt>git diff HEAD --</tt> to ask for the latter.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Without disambiguating <tt>--</tt>, git makes a reasonable guess, but errors\r
+   out and asking you to disambiguate when ambiguous.  E.g. if you have a\r
+   file called HEAD in your work tree, <tt>git diff HEAD</tt> is ambiguous, and\r
+   you have to say either <tt>git diff HEAD --</tt> or <tt>git diff -- HEAD</tt> to\r
+   disambiguate.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>When writing a script that is expected to handle random user-input, it is\r
+a good practice to make it explicit which arguments are which by placing\r
+disambiguating <tt>--</tt> at appropriate places.</p>\r
+<p>Here are the rules regarding the "flags" that you should follow when you are\r
+scripting git:</p>\r
 <ul>\r
 <li>\r
 <p>\r
@@ -310,7 +347,7 @@ when you give a revision parameter to a command, make sure the parameter is
 </li>\r
 </ul>\r
 </div>\r
-<h2>ENHANCED CLI</h2>\r
+<h2>ENHANCED OPTION PARSER</h2>\r
 <div class="sectionbody">\r
 <p>From the git 1.5.4 series and further, many git commands (not all of them at the\r
 time of the writing though) come with an enhanced option parser.</p>\r
@@ -388,7 +425,7 @@ $ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT</tt></pre>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 08-Jun-2008 01:34:28 UTC\r
+Last updated 28-Jun-2008 10:07:02 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/gitcli.txt b/gitcli.txt
index 8fb5d889e5757ad5c25717c4d9ed0a3ef378f794..23160498659a1e315ecd2976dfc348f28d26469c 100644 (file)
--- a/gitcli.txt
+++ b/gitcli.txt
@@ -13,8 +13,37 @@ gitcli
 DESCRIPTION
 -----------
 
-This manual describes best practice in how to use git CLI.  Here are
-the rules that you should follow when you are scripting git:
+This manual describes the convention used throughout git CLI.
+
+Many commands take revisions (most often "commits", but sometimes
+"tree-ish", depending on the context and command) and paths as their
+arguments.  Here are the rules:
+
+ * Revisions come first and then paths.
+   E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
+   `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
+   are paths.
+
+ * When an argument can be misunderstood as either a revision or a path,
+   they can be disambiguated by placing `\--` between them.
+   E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work
+   tree.  Please show changes between the version I staged in the index
+   and what I have in the work tree for that file". not "show difference
+   between the HEAD commit and the work tree as a whole".  You can say
+   `git diff HEAD \--` to ask for the latter.
+
+ * Without disambiguating `\--`, git makes a reasonable guess, but errors
+   out and asking you to disambiguate when ambiguous.  E.g. if you have a
+   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
+   you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to
+   disambiguate.
+
+When writing a script that is expected to handle random user-input, it is
+a good practice to make it explicit which arguments are which by placing
+disambiguating `\--` at appropriate places.
+
+Here are the rules regarding the "flags" that you should follow when you are
+scripting git:
 
  * it's preferred to use the non dashed form of git commands, which means that
    you should prefer `"git foo"` to `"git-foo"`.
@@ -34,8 +63,8 @@ the rules that you should follow when you are scripting git:
    if you happen to have a file called `HEAD` in the work tree.
 
 
-ENHANCED CLI
-------------
+ENHANCED OPTION PARSER
+----------------------
 From the git 1.5.4 series and further, many git commands (not all of them at the
 time of the writing though) come with an enhanced option parser.