parse-options: Add a gitcli(5) man page.
This page should hold every information about the git ways to parse command lines, and best practices to be used for scripting. Signed-off-by: Pierre Habouzit <madcoder@debian.org>
Pierre Habouzit committed
Dec 13, 2007 at 11:20 UTC
2f7ee089dff6e9225dbfca2bdd23efe93e1c0740
3 files changed
+115
-1
Documentation/Makefile
+1
-1
@@ -2,7 +2,7 @@ MAN1_TXT= \
2
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
3
$(wildcard git-*.txt)) \
4
gitk.txt
5
-MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt
5
+MAN5_TXT=gitattributes.txt gitignore.txt gitcli.txt gitmodules.txt
6
MAN7_TXT=git.txt
7
8
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
Documentation/gitcli.txt
new
+113
@@ -0,0 +1,113 @@
1
+gitcli(5)
2
+=========
3
+
4
+NAME
5
+----
6
+gitcli - git command line interface and conventions
7
+
8
+SYNOPSIS
9
+--------
10
+gitcli
11
+
12
+
13
+DESCRIPTION
14
+-----------
15
+
16
+This manual describes best practice in how to use git CLI. Here are
17
+the rules that you should follow when you are scripting git:
18
+
19
+ * it's preferred to use the non dashed form of git commands, which means that
20
+ you should prefer `"git foo"` to `"git-foo"`.
21
+
22
+ * splitting short options to separate words (prefer `"git foo -a -b"`
23
+ to `"git foo -ab"`, the latter may not even work).
24
+
25
+ * when a command line option takes an argument, use the 'sticked' form. In
26
+ other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short
27
+ options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"`
28
+ for long options. An option that takes optional option-argument must be
29
+ written in the 'sticked' form.
30
+
31
+ * when you give a revision parameter to a command, make sure the parameter is
32
+ not ambiguous with a name of a file in the work tree. E.g. do not write
33
+ `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work
34
+ if you happen to have a file called `HEAD` in the work tree.
35
+
36
+
37
+ENHANCED CLI
38
+------------
39
+From the git 1.5.4 series and further, many git commands (not all of them at the
40
+time of the writing though) come with an enhanced option parser.
41
+
42
+Here is an exhaustive list of the facilities provided by this option parser.
43
+
44
+
45
+Magic Options
46
+~~~~~~~~~~~~~
47
+Commands which have the enhanced option parser activated all understand a
48
+couple of magic command line options:
49
+
50
+-h::
51
+ gives a pretty printed usage of the command.
52
++
53
+---------------------------------------------
54
+$ git describe -h
55
+usage: git-describe [options] <committish>*
56
+
57
+ --contains find the tag that comes after the commit
58
+ --debug debug search strategy on stderr
59
+ --all use any ref in .git/refs
60
+ --tags use any tag in .git/refs/tags
61
+ --abbrev [<n>] use <n> digits to display SHA-1s
62
+ --candidates <n> consider <n> most recent tags (default: 10)
63
+---------------------------------------------
64
+
65
+--help-all::
66
+ Some git commands take options that are only used for plumbing or that
67
+ are deprecated, and such options are hidden from the default usage. This
68
+ option gives the full list of options.
69
+
70
+
71
+Negating options
72
+~~~~~~~~~~~~~~~~
73
+Options with long option names can be negated by prefixing `"--no-"`. For
74
+example, `"git branch"` has the option `"--track"` which is 'on' by default. You
75
+can use `"--no-track"` to override that behaviour. The same goes for `"--color"`
76
+and `"--no-color"`.
77
+
78
+
79
+Aggregating short options
80
+~~~~~~~~~~~~~~~~~~~~~~~~~
81
+Commands that support the enhanced option parser allow you to aggregate short
82
+options. This means that you can for example use `"git rm -rf"` or
83
+`"git clean -fdx"`.
84
+
85
+
86
+Separating argument from the option
87
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88
+You can write the mandatory option parameter to an option as a separate
89
+word on the command line. That means that all the following uses work:
90
+
91
+----------------------------
92
+$ git foo --long-opt=Arg
93
+$ git foo --long-opt Arg
94
+$ git foo -oArg
95
+$ git foo -o Arg
96
+----------------------------
97
+
98
+However, this is *NOT* allowed for switches with an optionnal value, where the
99
+'sticked' form must be used:
100
+----------------------------
101
+$ git describe --abbrev HEAD # correct
102
+$ git describe --abbrev=10 HEAD # correct
103
+$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT
104
+----------------------------
105
+
106
+
107
+Documentation
108
+-------------
109
+Documentation by Pierre Habouzit.
110
+
111
+GIT
112
+---
113
+Part of the gitlink:git[7] suite
Makefile
+1
@@ -1173,6 +1173,7 @@ check-docs::
1173
documented,gitattributes | \
1174
documented,gitignore | \
1175
documented,gitmodules | \
1176
+ documented,gitcli | \
1177
documented,git-tools | \
1178
sentinel,not,matching,is,ok ) continue ;; \
1179
esac; \