El 13/12/2007, a las 11:27, Pierre Habouzit escribió:
This page should hold every information about the git ways to parse
command
lines, and best practices to be used for scripting.
Some feedback from a native English speaker follows...
@@ -0,0 +1,104 @@
+gitcli(5)
+=========
+
+NAME
+----
+gitcli - git command line interface and its usual conventions
"git command line interface and conventions" sounds better; the
"usual" is redundant.
Or did you mean "*usage* conventions"? If that is the case, "git
command line interface and usage" is better, but just "git command
line interface" is enough.
+DESCRIPTION
+-----------
+This manual intends to describe best practice in how to use git
CLI. Here are
+the rules that you should follow when you are scripting git:
Suggest "how to use the git CLI".
+ * it's preferred to use the non dashed form of git commands, which
means that
+ you should prefer `"git foo"` to `"git-foo"`.
"non-dashed", and in any case, this could be more concise. How about:
* the non-dashed form of git commands is preferred; use `"git foo"`
rather than
`"git-foo"`
+ * splitting short option switches in separate atoms (prefer `"git
foo -a -b"`
+ to `"git foo -ab"`, the latter may not even work).
"*split* short option switches *into* separate atoms"
And the comma before "the latter may not even work" should be a semi-
colon.
+ * when a command line switch takes an argument, use the 'sticked'
form, which
+ means that you must prefer `"git foo -oArg"` to `"git foo -o
Arg"` for short
+ option switches, and `"git foo --long-opt=Arg"` to `"git foo --
long-opt Arg"`
+ for long switches.
Again this could be more concise. Instead of:
"which means that you must prefer .... to ..."
you could just say:
"use ... instead of ..."
+ENHANCED CLI
+------------
+From the git 1.5.4 series and further, git commands (not all of
them at the
+time of the writing though) come with an enhanced option parser
with nice
+facilities. Here is an exhaustive list of them
How about:
"From git 1.5.4 onwards, many git commands come with an enhanced
option parser..."
+Magic Options
+~~~~~~~~~~~~~
+Commands which have the enhanced option parser activated all
understand a
+couple of magic command line switches:
"Commands which use the enhanced option parser all understand..."
+
+-h::
+ gives a pretty printed usage of the command.
"pretty-printed"
+--help-all::
+ Some git commands takes options that are only used for plumbing or
that
+ are deprecated, and such options are hidden from the default
usage. This
+ switch gives the full list of options.
"Some git commands *take* options that are deprecated or used only
*by* plumbing"
And:
"such options are *not included in* the default usage" ("hidden from"
sounds awkward).
+Negating options
+~~~~~~~~~~~~~~~~
+Another things to keep in mind is that long options can be negated.
"Another *thing*"
But you could replace the whole sentence with just:
"Long options can be negated."
+Separating argument from the switch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Separating *the* argument from the switch"
Or if you prefer
"Separating *arguments* from the *switches*"
+However, this is *NOT* possible for switches with an optionnal
value, where the
+'sticked' form must be used:
Typo: "optional"
Cheers,
Wincent
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
