Commit | Line | Data |
---|---|---|
6d0618a8 | 1 | Like other projects, we also have some guidelines to keep to the |
6c3b2afe | 2 | code. For Git in general, a few rough rules are: |
6d0618a8 JS |
3 | |
4 | - Most importantly, we never say "It's in POSIX; we'll happily | |
5 | ignore your needs should your system not conform to it." | |
6 | We live in the real world. | |
7 | ||
8 | - However, we often say "Let's stay away from that construct, | |
9 | it's not even in POSIX". | |
10 | ||
11 | - In spite of the above two rules, we sometimes say "Although | |
12 | this is not in POSIX, it (is so convenient | makes the code | |
13 | much more readable | has other good characteristics) and | |
14 | practically all the platforms we care about support it, so | |
15 | let's use it". | |
16 | ||
17 | Again, we live in the real world, and it is sometimes a | |
18 | judgement call, the decision based more on real world | |
19 | constraints people face than what the paper standard says. | |
20 | ||
dd30800b JH |
21 | - Fixing style violations while working on a real change as a |
22 | preparatory clean-up step is good, but otherwise avoid useless code | |
23 | churn for the sake of conforming to the style. | |
24 | ||
25 | "Once it _is_ in the tree, it's not really worth the patch noise to | |
26 | go and fix it up." | |
2e477d8d | 27 | Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html |
dd30800b | 28 | |
c5e366b1 | 29 | Make your code readable and sensible, and don't try to be clever. |
6d0618a8 JS |
30 | |
31 | As for more concrete guidelines, just imitate the existing code | |
32 | (this is a good guideline, no matter which project you are | |
dfb047b9 | 33 | contributing to). It is always preferable to match the _local_ |
2de9b711 | 34 | convention. New code added to Git suite is expected to match |
dfb047b9 NS |
35 | the overall style of existing code. Modifications to existing |
36 | code is expected to match the style the surrounding code already | |
37 | uses (even if it doesn't match the overall style of existing code). | |
38 | ||
39 | But if you must have a list of rules, here they are. | |
6d0618a8 JS |
40 | |
41 | For shell scripts specifically (not exhaustive): | |
42 | ||
f36a4fa8 GB |
43 | - We use tabs for indentation. |
44 | ||
79fc3ca1 JH |
45 | - Case arms are indented at the same depth as case and esac lines, |
46 | like this: | |
47 | ||
48 | case "$variable" in | |
49 | pattern1) | |
50 | do this | |
51 | ;; | |
52 | pattern2) | |
53 | do that | |
54 | ;; | |
55 | esac | |
f36a4fa8 | 56 | |
48f359bf TH |
57 | - Redirection operators should be written with space before, but no |
58 | space after them. In other words, write 'echo test >"$file"' | |
59 | instead of 'echo test> $file' or 'echo test > $file'. Note that | |
60 | even though it is not required by POSIX to double-quote the | |
61 | redirection target in a variable (as shown above), our code does so | |
62 | because some versions of bash issue a warning without the quotes. | |
63 | ||
6a49909b JH |
64 | (incorrect) |
65 | cat hello > world < universe | |
66 | echo hello >$world | |
67 | ||
68 | (correct) | |
69 | cat hello >world <universe | |
70 | echo hello >"$world" | |
71 | ||
6d0618a8 JS |
72 | - We prefer $( ... ) for command substitution; unlike ``, it |
73 | properly nests. It should have been the way Bourne spelled | |
74 | it from day one, but unfortunately isn't. | |
75 | ||
860f70f9 TH |
76 | - If you want to find out if a command is available on the user's |
77 | $PATH, you should use 'type <command>', instead of 'which <command>'. | |
031fd4b9 | 78 | The output of 'which' is not machine parsable and its exit code |
860f70f9 TH |
79 | is not reliable across platforms. |
80 | ||
bc979945 JH |
81 | - We use POSIX compliant parameter substitutions and avoid bashisms; |
82 | namely: | |
6d0618a8 | 83 | |
bc979945 JH |
84 | - We use ${parameter-word} and its [-=?+] siblings, and their |
85 | colon'ed "unset or null" form. | |
6d0618a8 | 86 | |
bc979945 JH |
87 | - We use ${parameter#word} and its [#%] siblings, and their |
88 | doubled "longest matching" form. | |
6d0618a8 | 89 | |
bc979945 | 90 | - No "Substring Expansion" ${parameter:offset:length}. |
055467dd | 91 | |
bc979945 | 92 | - No shell arrays. |
6d0618a8 | 93 | |
bc979945 | 94 | - No strlen ${#parameter}. |
6d0618a8 | 95 | |
bc979945 | 96 | - No pattern replacement ${parameter/pattern/string}. |
6d0618a8 | 97 | |
bc979945 JH |
98 | - We use Arithmetic Expansion $(( ... )). |
99 | ||
100 | - Inside Arithmetic Expansion, spell shell variables with $ in front | |
101 | of them, as some shells do not grok $((x)) while accepting $(($x)) | |
102 | just fine (e.g. dash older than 0.5.4). | |
6d0618a8 JS |
103 | |
104 | - We do not use Process Substitution <(list) or >(list). | |
105 | ||
03b05c7d HV |
106 | - Do not write control structures on a single line with semicolon. |
107 | "then" should be on the next line for if statements, and "do" | |
108 | should be on the next line for "while" and "for". | |
109 | ||
9dbe7801 JH |
110 | (incorrect) |
111 | if test -f hello; then | |
112 | do this | |
113 | fi | |
114 | ||
115 | (correct) | |
116 | if test -f hello | |
117 | then | |
118 | do this | |
119 | fi | |
120 | ||
a378fee5 MD |
121 | - If a command sequence joined with && or || or | spans multiple |
122 | lines, put each command on a separate line and put && and || and | | |
123 | operators at the end of each line, rather than the start. This | |
124 | means you don't need to use \ to join lines, since the above | |
125 | operators imply the sequence isn't finished. | |
126 | ||
127 | (incorrect) | |
128 | grep blob verify_pack_result \ | |
129 | | awk -f print_1.awk \ | |
130 | | sort >actual && | |
131 | ... | |
132 | ||
133 | (correct) | |
134 | grep blob verify_pack_result | | |
135 | awk -f print_1.awk | | |
136 | sort >actual && | |
137 | ... | |
138 | ||
6d0618a8 JS |
139 | - We prefer "test" over "[ ... ]". |
140 | ||
141 | - We do not write the noiseword "function" in front of shell | |
142 | functions. | |
143 | ||
6117a3d4 JH |
144 | - We prefer a space between the function name and the parentheses, |
145 | and no space inside the parentheses. The opening "{" should also | |
146 | be on the same line. | |
147 | ||
148 | (incorrect) | |
149 | my_function(){ | |
150 | ... | |
151 | ||
152 | (correct) | |
153 | my_function () { | |
154 | ... | |
03b05c7d | 155 | |
009c98ee | 156 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
a58088ab | 157 | [::], [==], or [..]) for portability. |
009c98ee JH |
158 | |
159 | - We do not use \{m,n\}; | |
160 | ||
161 | - We do not use -E; | |
162 | ||
a58088ab | 163 | - We do not use ? or + (which are \{0,1\} and \{1,\} |
009c98ee JH |
164 | respectively in BRE) but that goes without saying as these |
165 | are ERE elements not BRE (note that \? and \+ are not even part | |
166 | of BRE -- making them accessible from BRE is a GNU extension). | |
167 | ||
5e9637c6 ÆAB |
168 | - Use Git's gettext wrappers in git-sh-i18n to make the user |
169 | interface translatable. See "Marking strings for translation" in | |
170 | po/README. | |
171 | ||
897f964c JH |
172 | - We do not write our "test" command with "-a" and "-o" and use "&&" |
173 | or "||" to concatenate multiple "test" commands instead, because | |
174 | the use of "-a/-o" is often error-prone. E.g. | |
175 | ||
176 | test -n "$x" -a "$a" = "$b" | |
177 | ||
178 | is buggy and breaks when $x is "=", but | |
179 | ||
180 | test -n "$x" && test "$a" = "$b" | |
181 | ||
182 | does not have such a problem. | |
183 | ||
184 | ||
6d0618a8 JS |
185 | For C programs: |
186 | ||
187 | - We use tabs to indent, and interpret tabs as taking up to | |
188 | 8 spaces. | |
189 | ||
190 | - We try to keep to at most 80 characters per line. | |
191 | ||
658df95a LS |
192 | - As a Git developer we assume you have a reasonably modern compiler |
193 | and we recommend you to enable the DEVELOPER makefile knob to | |
194 | ensure your patch is clear of all compiler warnings we care about, | |
195 | by e.g. "echo DEVELOPER=1 >>config.mak". | |
196 | ||
2de9b711 | 197 | - We try to support a wide range of C compilers to compile Git with, |
cc0c4297 JH |
198 | including old ones. You should not use features from newer C |
199 | standard, even if your compiler groks them. | |
a26fd033 | 200 | |
cc0c4297 JH |
201 | There are a few exceptions to this guideline: |
202 | ||
203 | . since early 2012 with e1327023ea, we have been using an enum | |
204 | definition whose last element is followed by a comma. This, like | |
205 | an array initializer that ends with a trailing comma, can be used | |
031fd4b9 | 206 | to reduce the patch noise when adding a new identifier at the end. |
cc0c4297 JH |
207 | |
208 | . since mid 2017 with cbc0f81d, we have been using designated | |
209 | initializers for struct (e.g. "struct t v = { .val = 'a' };"). | |
210 | ||
211 | . since mid 2017 with 512f41cf, we have been using designated | |
212 | initializers for array (e.g. "int array[10] = { [5] = 2 }"). | |
213 | ||
214 | These used to be forbidden, but we have not heard any breakage | |
215 | report, and they are assumed to be safe. | |
216 | ||
217 | - Variables have to be declared at the beginning of the block, before | |
218 | the first statement (i.e. -Wdeclaration-after-statement). | |
219 | ||
220 | - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)" | |
221 | is still not allowed in this codebase. | |
a26fd033 AS |
222 | |
223 | - NULL pointers shall be written as NULL, not as 0. | |
224 | ||
6d0618a8 JS |
225 | - When declaring pointers, the star sides with the variable |
226 | name, i.e. "char *string", not "char* string" or | |
227 | "char * string". This makes it easier to understand code | |
228 | like "char *string, c;". | |
229 | ||
f57b6cfd JK |
230 | - Use whitespace around operators and keywords, but not inside |
231 | parentheses and not around functions. So: | |
232 | ||
233 | while (condition) | |
234 | func(bar + 1); | |
235 | ||
236 | and not: | |
237 | ||
238 | while( condition ) | |
239 | func (bar+1); | |
240 | ||
6d0618a8 JS |
241 | - We avoid using braces unnecessarily. I.e. |
242 | ||
243 | if (bla) { | |
244 | x = 1; | |
245 | } | |
246 | ||
1797dc51 JK |
247 | is frowned upon. But there are a few exceptions: |
248 | ||
249 | - When the statement extends over a few lines (e.g., a while loop | |
250 | with an embedded conditional, or a comment). E.g.: | |
251 | ||
252 | while (foo) { | |
253 | if (x) | |
254 | one(); | |
255 | else | |
256 | two(); | |
257 | } | |
258 | ||
259 | if (foo) { | |
260 | /* | |
261 | * This one requires some explanation, | |
262 | * so we're better off with braces to make | |
263 | * it obvious that the indentation is correct. | |
264 | */ | |
265 | doit(); | |
266 | } | |
267 | ||
268 | - When there are multiple arms to a conditional and some of them | |
269 | require braces, enclose even a single line block in braces for | |
270 | consistency. E.g.: | |
271 | ||
272 | if (foo) { | |
273 | doit(); | |
274 | } else { | |
275 | one(); | |
276 | two(); | |
277 | three(); | |
278 | } | |
6d0618a8 | 279 | |
691d0dd0 | 280 | - We try to avoid assignments in the condition of an "if" statement. |
0b0b8cd7 | 281 | |
6d0618a8 JS |
282 | - Try to make your code understandable. You may put comments |
283 | in, but comments invariably tend to stale out when the code | |
284 | they were describing changes. Often splitting a function | |
285 | into two makes the intention of the code much clearer. | |
286 | ||
b75a6ca7 | 287 | - Multi-line comments include their delimiters on separate lines from |
288 | the text. E.g. | |
289 | ||
290 | /* | |
291 | * A very long | |
292 | * multi-line comment. | |
293 | */ | |
294 | ||
cbcfd4e3 JH |
295 | Note however that a comment that explains a translatable string to |
296 | translators uses a convention of starting with a magic token | |
66f5f6dc | 297 | "TRANSLATORS: ", e.g. |
cbcfd4e3 | 298 | |
66f5f6dc ÆAB |
299 | /* |
300 | * TRANSLATORS: here is a comment that explains the string to | |
301 | * be translated, that follows immediately after it. | |
302 | */ | |
cbcfd4e3 JH |
303 | _("Here is a translatable string explained by the above."); |
304 | ||
6d0618a8 JS |
305 | - Double negation is often harder to understand than no negation |
306 | at all. | |
307 | ||
5db9ab82 JH |
308 | - There are two schools of thought when it comes to comparison, |
309 | especially inside a loop. Some people prefer to have the less stable | |
310 | value on the left hand side and the more stable value on the right hand | |
311 | side, e.g. if you have a loop that counts variable i down to the | |
312 | lower bound, | |
313 | ||
314 | while (i > lower_bound) { | |
315 | do something; | |
316 | i--; | |
317 | } | |
318 | ||
319 | Other people prefer to have the textual order of values match the | |
320 | actual order of values in their comparison, so that they can | |
321 | mentally draw a number line from left to right and place these | |
322 | values in order, i.e. | |
323 | ||
324 | while (lower_bound < i) { | |
325 | do something; | |
326 | i--; | |
327 | } | |
328 | ||
329 | Both are valid, and we use both. However, the more "stable" the | |
330 | stable side becomes, the more we tend to prefer the former | |
331 | (comparison with a constant, "i > 0", is an extreme example). | |
332 | Just do not mix styles in the same part of the code and mimic | |
333 | existing styles in the neighbourhood. | |
334 | ||
f26443da JH |
335 | - There are two schools of thought when it comes to splitting a long |
336 | logical line into multiple lines. Some people push the second and | |
337 | subsequent lines far enough to the right with tabs and align them: | |
338 | ||
339 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
340 | span_more_than_a_single_line_of || | |
341 | the_source_text) { | |
342 | ... | |
343 | ||
344 | while other people prefer to align the second and the subsequent | |
345 | lines with the column immediately inside the opening parenthesis, | |
346 | with tabs and spaces, following our "tabstop is always a multiple | |
347 | of 8" convention: | |
348 | ||
349 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
350 | span_more_than_a_single_line_of || | |
351 | the_source_text) { | |
352 | ... | |
353 | ||
354 | Both are valid, and we use both. Again, just do not mix styles in | |
355 | the same part of the code and mimic existing styles in the | |
356 | neighbourhood. | |
357 | ||
358 | - When splitting a long logical line, some people change line before | |
359 | a binary operator, so that the result looks like a parse tree when | |
360 | you turn your head 90-degrees counterclockwise: | |
361 | ||
362 | if (the_beginning_of_a_very_long_expression_that_has_to | |
363 | || span_more_than_a_single_line_of_the_source_text) { | |
364 | ||
365 | while other people prefer to leave the operator at the end of the | |
366 | line: | |
367 | ||
368 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
369 | span_more_than_a_single_line_of_the_source_text) { | |
370 | ||
371 | Both are valid, but we tend to use the latter more, unless the | |
372 | expression gets fairly complex, in which case the former tends to | |
373 | be easier to read. Again, just do not mix styles in the same part | |
374 | of the code and mimic existing styles in the neighbourhood. | |
375 | ||
376 | - When splitting a long logical line, with everything else being | |
377 | equal, it is preferable to split after the operator at higher | |
378 | level in the parse tree. That is, this is more preferable: | |
379 | ||
380 | if (a_very_long_variable * that_is_used_in + | |
381 | a_very_long_expression) { | |
382 | ... | |
383 | ||
384 | than | |
385 | ||
386 | if (a_very_long_variable * | |
387 | that_is_used_in + a_very_long_expression) { | |
388 | ... | |
389 | ||
6d0618a8 JS |
390 | - Some clever tricks, like using the !! operator with arithmetic |
391 | constructs, can be extremely confusing to others. Avoid them, | |
392 | unless there is a compelling reason to use them. | |
393 | ||
394 | - Use the API. No, really. We have a strbuf (variable length | |
395 | string), several arrays with the ALLOC_GROW() macro, a | |
c455c87c | 396 | string_list for sorted string lists, a hash map (mapping struct |
6d0618a8 JS |
397 | objects) named "struct decorate", amongst other things. |
398 | ||
d9f079ad JH |
399 | - When you come up with an API, document its functions and structures |
400 | in the header file that exposes the API to its callers. Use what is | |
401 | in "strbuf.h" as a model for the appropriate tone and level of | |
402 | detail. | |
6d0618a8 | 403 | |
412cb2ec JH |
404 | - The first #include in C files, except in platform specific compat/ |
405 | implementations, must be either "git-compat-util.h", "cache.h" or | |
406 | "builtin.h". You do not have to include more than one of these. | |
407 | ||
408 | - A C file must directly include the header files that declare the | |
409 | functions and the types it uses, except for the functions and types | |
410 | that are made available to it by including one of the header files | |
411 | it must include by the previous rule. | |
6d0618a8 JS |
412 | |
413 | - If you are planning a new command, consider writing it in shell | |
414 | or perl first, so that changes in semantics can be easily | |
2de9b711 | 415 | changed and discussed. Many Git commands started out like |
6d0618a8 JS |
416 | that, and a few are still scripts. |
417 | ||
2de9b711 | 418 | - Avoid introducing a new dependency into Git. This means you |
6d0618a8 | 419 | usually should stay away from scripting languages not already |
2de9b711 | 420 | used in the Git core command set (unless your command is clearly |
6d0618a8 | 421 | separate from it, such as an importer to convert random-scm-X |
2de9b711 | 422 | repositories to Git). |
57199892 KB |
423 | |
424 | - When we pass <string, length> pair to functions, we should try to | |
425 | pass them in that order. | |
c455bd89 | 426 | |
5e9637c6 ÆAB |
427 | - Use Git's gettext wrappers to make the user interface |
428 | translatable. See "Marking strings for translation" in po/README. | |
429 | ||
89a9f2c8 JK |
430 | - Variables and functions local to a given source file should be marked |
431 | with "static". Variables that are visible to other source files | |
432 | must be declared with "extern" in header files. However, function | |
433 | declarations should not use "extern", as that is already the default. | |
434 | ||
f547101b ES |
435 | - You can launch gdb around your program using the shorthand GIT_DEBUGGER. |
436 | Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or | |
437 | run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to | |
438 | use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" | |
439 | ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) | |
440 | ||
c5e366b1 TZ |
441 | For Perl programs: |
442 | ||
443 | - Most of the C guidelines above apply. | |
444 | ||
445 | - We try to support Perl 5.8 and later ("use Perl 5.008"). | |
446 | ||
447 | - use strict and use warnings are strongly preferred. | |
448 | ||
449 | - Don't overuse statement modifiers unless using them makes the | |
450 | result easier to follow. | |
451 | ||
452 | ... do something ... | |
453 | do_this() unless (condition); | |
454 | ... do something else ... | |
455 | ||
456 | is more readable than: | |
457 | ||
458 | ... do something ... | |
459 | unless (condition) { | |
460 | do_this(); | |
461 | } | |
462 | ... do something else ... | |
463 | ||
464 | *only* when the condition is so rare that do_this() will be almost | |
465 | always called. | |
466 | ||
467 | - We try to avoid assignments inside "if ()" conditions. | |
468 | ||
469 | - Learn and use Git.pm if you need that functionality. | |
470 | ||
471 | - For Emacs, it's useful to put the following in | |
472 | GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: | |
473 | ||
474 | ;; note the first part is useful for C editing, too | |
475 | ((nil . ((indent-tabs-mode . t) | |
476 | (tab-width . 8) | |
477 | (fill-column . 80))) | |
478 | (cperl-mode . ((cperl-indent-level . 8) | |
479 | (cperl-extra-newline-before-brace . nil) | |
480 | (cperl-merge-trailing-else . t)))) | |
481 | ||
9ef43dd7 JK |
482 | For Python scripts: |
483 | ||
484 | - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). | |
485 | ||
486 | - As a minimum, we aim to be compatible with Python 2.6 and 2.7. | |
487 | ||
488 | - Where required libraries do not restrict us to Python 2, we try to | |
489 | also be compatible with Python 3.1 and later. | |
490 | ||
491 | - When you must differentiate between Unicode literals and byte string | |
492 | literals, it is OK to use the 'b' prefix. Even though the Python | |
493 | documentation for version 2.6 does not mention this prefix, it has | |
494 | been supported since version 2.6.0. | |
495 | ||
0ae0e882 PO |
496 | Error Messages |
497 | ||
498 | - Do not end error messages with a full stop. | |
499 | ||
500 | - Do not capitalize ("unable to open %s", not "Unable to open %s") | |
501 | ||
502 | - Say what the error is first ("cannot open %s", not "%s: cannot open") | |
503 | ||
504 | ||
35840a3e JH |
505 | Externally Visible Names |
506 | ||
507 | - For configuration variable names, follow the existing convention: | |
508 | ||
509 | . The section name indicates the affected subsystem. | |
510 | ||
511 | . The subsection name, if any, indicates which of an unbounded set | |
512 | of things to set the value for. | |
513 | ||
514 | . The variable name describes the effect of tweaking this knob. | |
515 | ||
516 | The section and variable names that consist of multiple words are | |
517 | formed by concatenating the words without punctuations (e.g. `-`), | |
518 | and are broken using bumpyCaps in documentation as a hint to the | |
519 | reader. | |
520 | ||
521 | When choosing the variable namespace, do not use variable name for | |
522 | specifying possibly unbounded set of things, most notably anything | |
523 | an end user can freely come up with (e.g. branch names). Instead, | |
524 | use subsection names or variable values, like the existing variable | |
525 | branch.<name>.description does. | |
526 | ||
527 | ||
c455bd89 ŠN |
528 | Writing Documentation: |
529 | ||
48bc1755 DW |
530 | Most (if not all) of the documentation pages are written in the |
531 | AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and | |
532 | processed into HTML and manpages (e.g. git.html and git.1 in the | |
533 | same directory). | |
bb9f2aec | 534 | |
42e0fae9 MB |
535 | The documentation liberally mixes US and UK English (en_US/UK) |
536 | norms for spelling and grammar, which is somewhat unfortunate. | |
537 | In an ideal world, it would have been better if it consistently | |
538 | used only one and not the other, and we would have picked en_US | |
539 | (if you wish to correct the English of some of the existing | |
540 | documentation, please see the documentation-related advice in the | |
541 | Documentation/SubmittingPatches file). | |
542 | ||
c455bd89 ŠN |
543 | Every user-visible change should be reflected in the documentation. |
544 | The same general rule as for code applies -- imitate the existing | |
ca03c368 JSJ |
545 | conventions. |
546 | ||
547 | A few commented examples follow to provide reference when writing or | |
548 | modifying command usage strings and synopsis sections in the manual | |
549 | pages: | |
c455bd89 | 550 | |
b1afe49d | 551 | Placeholders are spelled in lowercase and enclosed in angle brackets: |
c455bd89 ŠN |
552 | <file> |
553 | --sort=<key> | |
554 | --abbrev[=<n>] | |
555 | ||
9c9b4f2f AH |
556 | If a placeholder has multiple words, they are separated by dashes: |
557 | <new-branch-name> | |
558 | --template=<template-directory> | |
559 | ||
469bfc96 | 560 | Possibility of multiple occurrences is indicated by three dots: |
c455bd89 ŠN |
561 | <file>... |
562 | (One or more of <file>.) | |
563 | ||
564 | Optional parts are enclosed in square brackets: | |
565 | [<extra>] | |
566 | (Zero or one <extra>.) | |
567 | ||
568 | --exec-path[=<path>] | |
569 | (Option with an optional argument. Note that the "=" is inside the | |
570 | brackets.) | |
571 | ||
572 | [<patch>...] | |
573 | (Zero or more of <patch>. Note that the dots are inside, not | |
574 | outside the brackets.) | |
575 | ||
9c9b4f2f | 576 | Multiple alternatives are indicated with vertical bars: |
c455bd89 ŠN |
577 | [-q | --quiet] |
578 | [--utf8 | --no-utf8] | |
579 | ||
580 | Parentheses are used for grouping: | |
9c9b4f2f | 581 | [(<rev> | <range>)...] |
c455bd89 ŠN |
582 | (Any number of either <rev> or <range>. Parens are needed to make |
583 | it clear that "..." pertains to both <rev> and <range>.) | |
584 | ||
585 | [(-p <parent>)...] | |
586 | (Any number of option -p, each with one <parent> argument.) | |
587 | ||
588 | git remote set-head <name> (-a | -d | <branch>) | |
589 | (One and only one of "-a", "-d" or "<branch>" _must_ (no square | |
590 | brackets) be provided.) | |
591 | ||
592 | And a somewhat more contrived example: | |
593 | --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] | |
594 | Here "=" is outside the brackets, because "--diff-filter=" is a | |
595 | valid usage. "*" has its own pair of brackets, because it can | |
596 | (optionally) be specified only when one or more of the letters is | |
597 | also provided. | |
48a8c26c TA |
598 | |
599 | A note on notation: | |
600 | Use 'git' (all lowercase) when talking about commands i.e. something | |
601 | the user would type into a shell and use 'Git' (uppercase first letter) | |
602 | when talking about the version control system and its properties. | |
ca03c368 JSJ |
603 | |
604 | A few commented examples follow to provide reference when writing or | |
605 | modifying paragraphs or option/command explanations that contain options | |
606 | or commands: | |
607 | ||
41f5b21f | 608 | Literal examples (e.g. use of command-line options, command names, |
0dbd305f CB |
609 | branch names, URLs, pathnames (files and directories), configuration and |
610 | environment variables) must be typeset in monospace (i.e. wrapped with | |
611 | backticks): | |
ca03c368 JSJ |
612 | `--pretty=oneline` |
613 | `git rev-list` | |
da0005b8 | 614 | `remote.pushDefault` |
0dbd305f CB |
615 | `http://git.example.com` |
616 | `.git/config` | |
41f5b21f | 617 | `GIT_DIR` |
57103dbf | 618 | `HEAD` |
41f5b21f TR |
619 | |
620 | An environment variable must be prefixed with "$" only when referring to its | |
621 | value and not when referring to the variable itself, in this case there is | |
622 | nothing to add except the backticks: | |
623 | `GIT_DIR` is specified | |
624 | `$GIT_DIR/hooks/pre-receive` | |
ca03c368 JSJ |
625 | |
626 | Word phrases enclosed in `backtick characters` are rendered literally | |
627 | and will not be further expanded. The use of `backticks` to achieve the | |
628 | previous rule means that literal examples should not use AsciiDoc | |
629 | escapes. | |
630 | Correct: | |
631 | `--pretty=oneline` | |
632 | Incorrect: | |
633 | `\--pretty=oneline` | |
634 | ||
635 | If some place in the documentation needs to typeset a command usage | |
636 | example with inline substitutions, it is fine to use +monospaced and | |
637 | inline substituted text+ instead of `monospaced literal text`, and with | |
638 | the former, the part that should not get substituted must be | |
639 | quoted/escaped. |