]>
Commit | Line | Data |
---|---|---|
2f7ee089 PH |
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 | --- | |
5162e697 | 113 | Part of the linkgit:git[7] suite |