]>
Commit | Line | Data |
---|---|---|
cf6cac20 EN |
1 | Like other projects, we also have some guidelines for our code. For |
2 | 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." | |
ffbf6a74 | 27 | Cf. https://lore.kernel.org/all/20100126160632.3bdbe172.akpm@linux-foundation.org/ |
dd30800b | 28 | |
607817a3 JH |
29 | - Log messages to explain your changes are as important as the |
30 | changes themselves. Clearly written code and in-code comments | |
31 | explain how the code works and what is assumed from the surrounding | |
32 | context. The log messages explain what the changes wanted to | |
33 | achieve and why the changes were necessary (more on this in the | |
34 | accompanying SubmittingPatches document). | |
35 | ||
c5e366b1 | 36 | Make your code readable and sensible, and don't try to be clever. |
6d0618a8 JS |
37 | |
38 | As for more concrete guidelines, just imitate the existing code | |
39 | (this is a good guideline, no matter which project you are | |
dfb047b9 | 40 | contributing to). It is always preferable to match the _local_ |
2de9b711 | 41 | convention. New code added to Git suite is expected to match |
dfb047b9 | 42 | the overall style of existing code. Modifications to existing |
ce14cc0b | 43 | code are expected to match the style the surrounding code already |
dfb047b9 NS |
44 | uses (even if it doesn't match the overall style of existing code). |
45 | ||
7a06a854 CG |
46 | But if you must have a list of rules, here are some language |
47 | specific ones. Note that Documentation/ToolsForGit.txt document | |
48 | has a collection of tips to help you use some external tools | |
49 | to conform to these guidelines. | |
6d0618a8 JS |
50 | |
51 | For shell scripts specifically (not exhaustive): | |
52 | ||
f36a4fa8 GB |
53 | - We use tabs for indentation. |
54 | ||
79fc3ca1 JH |
55 | - Case arms are indented at the same depth as case and esac lines, |
56 | like this: | |
57 | ||
58 | case "$variable" in | |
59 | pattern1) | |
60 | do this | |
61 | ;; | |
62 | pattern2) | |
63 | do that | |
64 | ;; | |
65 | esac | |
f36a4fa8 | 66 | |
48f359bf TH |
67 | - Redirection operators should be written with space before, but no |
68 | space after them. In other words, write 'echo test >"$file"' | |
69 | instead of 'echo test> $file' or 'echo test > $file'. Note that | |
70 | even though it is not required by POSIX to double-quote the | |
71 | redirection target in a variable (as shown above), our code does so | |
72 | because some versions of bash issue a warning without the quotes. | |
73 | ||
6a49909b JH |
74 | (incorrect) |
75 | cat hello > world < universe | |
76 | echo hello >$world | |
77 | ||
78 | (correct) | |
79 | cat hello >world <universe | |
80 | echo hello >"$world" | |
81 | ||
6d0618a8 JS |
82 | - We prefer $( ... ) for command substitution; unlike ``, it |
83 | properly nests. It should have been the way Bourne spelled | |
84 | it from day one, but unfortunately isn't. | |
85 | ||
860f70f9 TH |
86 | - If you want to find out if a command is available on the user's |
87 | $PATH, you should use 'type <command>', instead of 'which <command>'. | |
031fd4b9 | 88 | The output of 'which' is not machine parsable and its exit code |
860f70f9 TH |
89 | is not reliable across platforms. |
90 | ||
bc979945 JH |
91 | - We use POSIX compliant parameter substitutions and avoid bashisms; |
92 | namely: | |
6d0618a8 | 93 | |
bc979945 JH |
94 | - We use ${parameter-word} and its [-=?+] siblings, and their |
95 | colon'ed "unset or null" form. | |
6d0618a8 | 96 | |
bc979945 JH |
97 | - We use ${parameter#word} and its [#%] siblings, and their |
98 | doubled "longest matching" form. | |
6d0618a8 | 99 | |
bc979945 | 100 | - No "Substring Expansion" ${parameter:offset:length}. |
055467dd | 101 | |
bc979945 | 102 | - No shell arrays. |
6d0618a8 | 103 | |
bc979945 | 104 | - No pattern replacement ${parameter/pattern/string}. |
6d0618a8 | 105 | |
bc979945 JH |
106 | - We use Arithmetic Expansion $(( ... )). |
107 | ||
6d0618a8 JS |
108 | - We do not use Process Substitution <(list) or >(list). |
109 | ||
03b05c7d HV |
110 | - Do not write control structures on a single line with semicolon. |
111 | "then" should be on the next line for if statements, and "do" | |
112 | should be on the next line for "while" and "for". | |
113 | ||
9dbe7801 JH |
114 | (incorrect) |
115 | if test -f hello; then | |
116 | do this | |
117 | fi | |
118 | ||
119 | (correct) | |
120 | if test -f hello | |
121 | then | |
122 | do this | |
123 | fi | |
124 | ||
a378fee5 MD |
125 | - If a command sequence joined with && or || or | spans multiple |
126 | lines, put each command on a separate line and put && and || and | | |
127 | operators at the end of each line, rather than the start. This | |
128 | means you don't need to use \ to join lines, since the above | |
129 | operators imply the sequence isn't finished. | |
130 | ||
131 | (incorrect) | |
132 | grep blob verify_pack_result \ | |
133 | | awk -f print_1.awk \ | |
134 | | sort >actual && | |
135 | ... | |
136 | ||
137 | (correct) | |
138 | grep blob verify_pack_result | | |
139 | awk -f print_1.awk | | |
140 | sort >actual && | |
141 | ... | |
142 | ||
6d0618a8 JS |
143 | - We prefer "test" over "[ ... ]". |
144 | ||
145 | - We do not write the noiseword "function" in front of shell | |
146 | functions. | |
147 | ||
6117a3d4 JH |
148 | - We prefer a space between the function name and the parentheses, |
149 | and no space inside the parentheses. The opening "{" should also | |
150 | be on the same line. | |
151 | ||
152 | (incorrect) | |
153 | my_function(){ | |
154 | ... | |
155 | ||
156 | (correct) | |
157 | my_function () { | |
158 | ... | |
03b05c7d | 159 | |
009c98ee | 160 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
a58088ab | 161 | [::], [==], or [..]) for portability. |
009c98ee JH |
162 | |
163 | - We do not use \{m,n\}; | |
164 | ||
a58088ab | 165 | - We do not use ? or + (which are \{0,1\} and \{1,\} |
009c98ee JH |
166 | respectively in BRE) but that goes without saying as these |
167 | are ERE elements not BRE (note that \? and \+ are not even part | |
168 | of BRE -- making them accessible from BRE is a GNU extension). | |
169 | ||
5e9637c6 ÆAB |
170 | - Use Git's gettext wrappers in git-sh-i18n to make the user |
171 | interface translatable. See "Marking strings for translation" in | |
172 | po/README. | |
173 | ||
897f964c JH |
174 | - We do not write our "test" command with "-a" and "-o" and use "&&" |
175 | or "||" to concatenate multiple "test" commands instead, because | |
176 | the use of "-a/-o" is often error-prone. E.g. | |
177 | ||
178 | test -n "$x" -a "$a" = "$b" | |
179 | ||
180 | is buggy and breaks when $x is "=", but | |
181 | ||
182 | test -n "$x" && test "$a" = "$b" | |
183 | ||
184 | does not have such a problem. | |
185 | ||
a84fd3bc JH |
186 | - Even though "local" is not part of POSIX, we make heavy use of it |
187 | in our test suite. We do not use it in scripted Porcelains, and | |
188 | hopefully nobody starts using "local" before they are reimplemented | |
189 | in C ;-) | |
190 | ||
7e3a9c23 JH |
191 | - Some versions of shell do not understand "export variable=value", |
192 | so we write "variable=value" and then "export variable" on two | |
193 | separate lines. | |
194 | ||
be34b510 JH |
195 | - Some versions of dash have broken variable assignment when prefixed |
196 | with "local", "export", and "readonly", in that the value to be | |
197 | assigned goes through field splitting at $IFS unless quoted. | |
198 | ||
199 | (incorrect) | |
200 | local variable=$value | |
201 | local variable=$(command args) | |
202 | ||
203 | (correct) | |
204 | local variable="$value" | |
205 | local variable="$(command args)" | |
206 | ||
f0b68f05 JT |
207 | - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. |
208 | "\xc2\xa2") in printf format strings, since hexadecimal escape | |
209 | sequences are not portable. | |
210 | ||
897f964c | 211 | |
6d0618a8 JS |
212 | For C programs: |
213 | ||
214 | - We use tabs to indent, and interpret tabs as taking up to | |
215 | 8 spaces. | |
216 | ||
217 | - We try to keep to at most 80 characters per line. | |
218 | ||
658df95a LS |
219 | - As a Git developer we assume you have a reasonably modern compiler |
220 | and we recommend you to enable the DEVELOPER makefile knob to | |
221 | ensure your patch is clear of all compiler warnings we care about, | |
222 | by e.g. "echo DEVELOPER=1 >>config.mak". | |
223 | ||
2de9b711 | 224 | - We try to support a wide range of C compilers to compile Git with, |
e88a2d02 ÆAB |
225 | including old ones. As of Git v2.35.0 Git requires C99 (we check |
226 | "__STDC_VERSION__"). You should not use features from a newer C | |
cc0c4297 | 227 | standard, even if your compiler groks them. |
a26fd033 | 228 | |
e88a2d02 ÆAB |
229 | New C99 features have been phased in gradually, if something's new |
230 | in C99 but not used yet don't assume that it's safe to use, some | |
231 | compilers we target have only partial support for it. These are | |
232 | considered safe to use: | |
cc0c4297 | 233 | |
442c27dd ÆAB |
234 | . since around 2007 with 2b6854c863a, we have been using |
235 | initializer elements which are not computable at load time. E.g.: | |
236 | ||
237 | const char *args[] = {"constant", variable, NULL}; | |
cc0c4297 JH |
238 | |
239 | . since early 2012 with e1327023ea, we have been using an enum | |
240 | definition whose last element is followed by a comma. This, like | |
241 | an array initializer that ends with a trailing comma, can be used | |
031fd4b9 | 242 | to reduce the patch noise when adding a new identifier at the end. |
cc0c4297 JH |
243 | |
244 | . since mid 2017 with cbc0f81d, we have been using designated | |
245 | initializers for struct (e.g. "struct t v = { .val = 'a' };"). | |
246 | ||
247 | . since mid 2017 with 512f41cf, we have been using designated | |
248 | initializers for array (e.g. "int array[10] = { [5] = 2 }"). | |
249 | ||
56a29d2c ÆAB |
250 | . since early 2021 with 765dc168882, we have been using variadic |
251 | macros, mostly for printf-like trace and debug macros. | |
252 | ||
82dd01d8 ÆAB |
253 | . since late 2021 with 44ba10d6, we have had variables declared in |
254 | the for loop "for (int i = 0; i < 10; i++)". | |
cc0c4297 | 255 | |
d7d850e2 ÆAB |
256 | New C99 features that we cannot use yet: |
257 | ||
258 | . %z and %zu as a printf() argument for a size_t (the %z being for | |
259 | the POSIX-specific ssize_t). Instead you should use | |
260 | printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we | |
261 | rely on supports %z, but the C library used by MinGW does not. | |
262 | ||
438c2f85 ÆAB |
263 | . Shorthand like ".a.b = *c" in struct initializations is known to |
264 | trip up an older IBM XLC version, use ".a = { .b = *c }" instead. | |
265 | See the 33665d98 (reftable: make assignments portable to AIX xlc | |
266 | v12.01, 2022-03-28). | |
cc0c4297 JH |
267 | |
268 | - Variables have to be declared at the beginning of the block, before | |
269 | the first statement (i.e. -Wdeclaration-after-statement). | |
270 | ||
a26fd033 AS |
271 | - NULL pointers shall be written as NULL, not as 0. |
272 | ||
6d0618a8 JS |
273 | - When declaring pointers, the star sides with the variable |
274 | name, i.e. "char *string", not "char* string" or | |
275 | "char * string". This makes it easier to understand code | |
276 | like "char *string, c;". | |
277 | ||
f57b6cfd JK |
278 | - Use whitespace around operators and keywords, but not inside |
279 | parentheses and not around functions. So: | |
280 | ||
281 | while (condition) | |
282 | func(bar + 1); | |
283 | ||
284 | and not: | |
285 | ||
286 | while( condition ) | |
287 | func (bar+1); | |
288 | ||
5c7bb014 JH |
289 | - Do not explicitly compare an integral value with constant 0 or '\0', |
290 | or a pointer value with constant NULL. For instance, to validate that | |
291 | counted array <ptr, cnt> is initialized but has no elements, write: | |
292 | ||
293 | if (!ptr || cnt) | |
294 | BUG("empty array expected"); | |
295 | ||
296 | and not: | |
297 | ||
298 | if (ptr == NULL || cnt != 0); | |
299 | BUG("empty array expected"); | |
300 | ||
6d0618a8 JS |
301 | - We avoid using braces unnecessarily. I.e. |
302 | ||
303 | if (bla) { | |
304 | x = 1; | |
305 | } | |
306 | ||
1797dc51 JK |
307 | is frowned upon. But there are a few exceptions: |
308 | ||
309 | - When the statement extends over a few lines (e.g., a while loop | |
310 | with an embedded conditional, or a comment). E.g.: | |
311 | ||
312 | while (foo) { | |
313 | if (x) | |
314 | one(); | |
315 | else | |
316 | two(); | |
317 | } | |
318 | ||
319 | if (foo) { | |
320 | /* | |
321 | * This one requires some explanation, | |
322 | * so we're better off with braces to make | |
323 | * it obvious that the indentation is correct. | |
324 | */ | |
325 | doit(); | |
326 | } | |
327 | ||
328 | - When there are multiple arms to a conditional and some of them | |
329 | require braces, enclose even a single line block in braces for | |
330 | consistency. E.g.: | |
331 | ||
332 | if (foo) { | |
333 | doit(); | |
334 | } else { | |
335 | one(); | |
336 | two(); | |
337 | three(); | |
338 | } | |
6d0618a8 | 339 | |
691d0dd0 | 340 | - We try to avoid assignments in the condition of an "if" statement. |
0b0b8cd7 | 341 | |
6d0618a8 JS |
342 | - Try to make your code understandable. You may put comments |
343 | in, but comments invariably tend to stale out when the code | |
344 | they were describing changes. Often splitting a function | |
345 | into two makes the intention of the code much clearer. | |
346 | ||
b75a6ca7 | 347 | - Multi-line comments include their delimiters on separate lines from |
348 | the text. E.g. | |
349 | ||
350 | /* | |
351 | * A very long | |
352 | * multi-line comment. | |
353 | */ | |
354 | ||
cbcfd4e3 JH |
355 | Note however that a comment that explains a translatable string to |
356 | translators uses a convention of starting with a magic token | |
66f5f6dc | 357 | "TRANSLATORS: ", e.g. |
cbcfd4e3 | 358 | |
66f5f6dc ÆAB |
359 | /* |
360 | * TRANSLATORS: here is a comment that explains the string to | |
361 | * be translated, that follows immediately after it. | |
362 | */ | |
cbcfd4e3 JH |
363 | _("Here is a translatable string explained by the above."); |
364 | ||
6d0618a8 JS |
365 | - Double negation is often harder to understand than no negation |
366 | at all. | |
367 | ||
5db9ab82 JH |
368 | - There are two schools of thought when it comes to comparison, |
369 | especially inside a loop. Some people prefer to have the less stable | |
370 | value on the left hand side and the more stable value on the right hand | |
371 | side, e.g. if you have a loop that counts variable i down to the | |
372 | lower bound, | |
373 | ||
374 | while (i > lower_bound) { | |
375 | do something; | |
376 | i--; | |
377 | } | |
378 | ||
379 | Other people prefer to have the textual order of values match the | |
380 | actual order of values in their comparison, so that they can | |
381 | mentally draw a number line from left to right and place these | |
382 | values in order, i.e. | |
383 | ||
384 | while (lower_bound < i) { | |
385 | do something; | |
386 | i--; | |
387 | } | |
388 | ||
389 | Both are valid, and we use both. However, the more "stable" the | |
390 | stable side becomes, the more we tend to prefer the former | |
391 | (comparison with a constant, "i > 0", is an extreme example). | |
392 | Just do not mix styles in the same part of the code and mimic | |
393 | existing styles in the neighbourhood. | |
394 | ||
f26443da JH |
395 | - There are two schools of thought when it comes to splitting a long |
396 | logical line into multiple lines. Some people push the second and | |
397 | subsequent lines far enough to the right with tabs and align them: | |
398 | ||
399 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
400 | span_more_than_a_single_line_of || | |
401 | the_source_text) { | |
402 | ... | |
403 | ||
404 | while other people prefer to align the second and the subsequent | |
405 | lines with the column immediately inside the opening parenthesis, | |
406 | with tabs and spaces, following our "tabstop is always a multiple | |
407 | of 8" convention: | |
408 | ||
409 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
410 | span_more_than_a_single_line_of || | |
411 | the_source_text) { | |
412 | ... | |
413 | ||
414 | Both are valid, and we use both. Again, just do not mix styles in | |
415 | the same part of the code and mimic existing styles in the | |
416 | neighbourhood. | |
417 | ||
418 | - When splitting a long logical line, some people change line before | |
419 | a binary operator, so that the result looks like a parse tree when | |
420 | you turn your head 90-degrees counterclockwise: | |
421 | ||
422 | if (the_beginning_of_a_very_long_expression_that_has_to | |
423 | || span_more_than_a_single_line_of_the_source_text) { | |
424 | ||
425 | while other people prefer to leave the operator at the end of the | |
426 | line: | |
427 | ||
428 | if (the_beginning_of_a_very_long_expression_that_has_to || | |
429 | span_more_than_a_single_line_of_the_source_text) { | |
430 | ||
431 | Both are valid, but we tend to use the latter more, unless the | |
432 | expression gets fairly complex, in which case the former tends to | |
433 | be easier to read. Again, just do not mix styles in the same part | |
434 | of the code and mimic existing styles in the neighbourhood. | |
435 | ||
436 | - When splitting a long logical line, with everything else being | |
437 | equal, it is preferable to split after the operator at higher | |
438 | level in the parse tree. That is, this is more preferable: | |
439 | ||
440 | if (a_very_long_variable * that_is_used_in + | |
441 | a_very_long_expression) { | |
442 | ... | |
443 | ||
444 | than | |
445 | ||
446 | if (a_very_long_variable * | |
447 | that_is_used_in + a_very_long_expression) { | |
448 | ... | |
449 | ||
6d0618a8 JS |
450 | - Some clever tricks, like using the !! operator with arithmetic |
451 | constructs, can be extremely confusing to others. Avoid them, | |
452 | unless there is a compelling reason to use them. | |
453 | ||
454 | - Use the API. No, really. We have a strbuf (variable length | |
455 | string), several arrays with the ALLOC_GROW() macro, a | |
c455c87c | 456 | string_list for sorted string lists, a hash map (mapping struct |
6d0618a8 JS |
457 | objects) named "struct decorate", amongst other things. |
458 | ||
d9f079ad JH |
459 | - When you come up with an API, document its functions and structures |
460 | in the header file that exposes the API to its callers. Use what is | |
461 | in "strbuf.h" as a model for the appropriate tone and level of | |
462 | detail. | |
6d0618a8 | 463 | |
412cb2ec | 464 | - The first #include in C files, except in platform specific compat/ |
4e89f0e0 JH |
465 | implementations and sha1dc/, must be <git-compat-util.h>. This |
466 | header file insulates other header files and source files from | |
467 | platform differences, like which system header files must be | |
468 | included in what order, and what C preprocessor feature macros must | |
469 | be defined to trigger certain features we expect out of the system. | |
470 | A collorary to this is that C files should not directly include | |
471 | system header files themselves. | |
472 | ||
473 | There are some exceptions, because certain group of files that | |
474 | implement an API all have to include the same header file that | |
475 | defines the API and it is convenient to include <git-compat-util.h> | |
476 | there. Namely: | |
477 | ||
478 | - the implementation of the built-in commands in the "builtin/" | |
479 | directory that include "builtin.h" for the cmd_foo() prototype | |
480 | definition, | |
481 | ||
482 | - the test helper programs in the "t/helper/" directory that include | |
483 | "t/helper/test-tool.h" for the cmd__foo() prototype definition, | |
484 | ||
485 | - the xdiff implementation in the "xdiff/" directory that includes | |
486 | "xdiff/xinclude.h" for the xdiff machinery internals, | |
487 | ||
488 | - the unit test programs in "t/unit-tests/" directory that include | |
489 | "t/unit-tests/test-lib.h" that gives them the unit-tests | |
490 | framework, and | |
491 | ||
492 | - the source files that implement reftable in the "reftable/" | |
493 | directory that include "reftable/system.h" for the reftable | |
494 | internals, | |
495 | ||
496 | are allowed to assume that they do not have to include | |
497 | <git-compat-util.h> themselves, as it is included as the first | |
498 | '#include' in these header files. These headers must be the first | |
499 | header file to be "#include"d in them, though. | |
412cb2ec JH |
500 | |
501 | - A C file must directly include the header files that declare the | |
502 | functions and the types it uses, except for the functions and types | |
503 | that are made available to it by including one of the header files | |
504 | it must include by the previous rule. | |
6d0618a8 JS |
505 | |
506 | - If you are planning a new command, consider writing it in shell | |
507 | or perl first, so that changes in semantics can be easily | |
2de9b711 | 508 | changed and discussed. Many Git commands started out like |
6d0618a8 JS |
509 | that, and a few are still scripts. |
510 | ||
2de9b711 | 511 | - Avoid introducing a new dependency into Git. This means you |
6d0618a8 | 512 | usually should stay away from scripting languages not already |
2de9b711 | 513 | used in the Git core command set (unless your command is clearly |
6d0618a8 | 514 | separate from it, such as an importer to convert random-scm-X |
2de9b711 | 515 | repositories to Git). |
57199892 KB |
516 | |
517 | - When we pass <string, length> pair to functions, we should try to | |
518 | pass them in that order. | |
c455bd89 | 519 | |
5e9637c6 ÆAB |
520 | - Use Git's gettext wrappers to make the user interface |
521 | translatable. See "Marking strings for translation" in po/README. | |
522 | ||
89a9f2c8 JK |
523 | - Variables and functions local to a given source file should be marked |
524 | with "static". Variables that are visible to other source files | |
525 | must be declared with "extern" in header files. However, function | |
526 | declarations should not use "extern", as that is already the default. | |
527 | ||
f547101b ES |
528 | - You can launch gdb around your program using the shorthand GIT_DEBUGGER. |
529 | Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or | |
530 | run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to | |
531 | use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" | |
532 | ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) | |
533 | ||
c5e366b1 TZ |
534 | For Perl programs: |
535 | ||
536 | - Most of the C guidelines above apply. | |
537 | ||
d13a73e3 | 538 | - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). |
c5e366b1 TZ |
539 | |
540 | - use strict and use warnings are strongly preferred. | |
541 | ||
542 | - Don't overuse statement modifiers unless using them makes the | |
543 | result easier to follow. | |
544 | ||
545 | ... do something ... | |
546 | do_this() unless (condition); | |
547 | ... do something else ... | |
548 | ||
549 | is more readable than: | |
550 | ||
551 | ... do something ... | |
552 | unless (condition) { | |
553 | do_this(); | |
554 | } | |
555 | ... do something else ... | |
556 | ||
557 | *only* when the condition is so rare that do_this() will be almost | |
558 | always called. | |
559 | ||
560 | - We try to avoid assignments inside "if ()" conditions. | |
561 | ||
562 | - Learn and use Git.pm if you need that functionality. | |
563 | ||
9ef43dd7 JK |
564 | For Python scripts: |
565 | ||
65175d9e | 566 | - We follow PEP-8 (https://peps.python.org/pep-0008/). |
9ef43dd7 | 567 | |
45a87a83 | 568 | - As a minimum, we aim to be compatible with Python 2.7. |
9ef43dd7 JK |
569 | |
570 | - Where required libraries do not restrict us to Python 2, we try to | |
571 | also be compatible with Python 3.1 and later. | |
572 | ||
e258eb48 ES |
573 | |
574 | Program Output | |
575 | ||
576 | We make a distinction between a Git command's primary output and | |
577 | output which is merely chatty feedback (for instance, status | |
578 | messages, running transcript, or progress display), as well as error | |
579 | messages. Roughly speaking, a Git command's primary output is that | |
580 | which one might want to capture to a file or send down a pipe; its | |
581 | chatty output should not interfere with these use-cases. | |
582 | ||
583 | As such, primary output should be sent to the standard output stream | |
584 | (stdout), and chatty output should be sent to the standard error | |
585 | stream (stderr). Examples of commands which produce primary output | |
586 | include `git log`, `git show`, and `git branch --list` which generate | |
587 | output on the stdout stream. | |
588 | ||
589 | Not all Git commands have primary output; this is often true of | |
590 | commands whose main function is to perform an action. Some action | |
591 | commands are silent, whereas others are chatty. An example of a | |
592 | chatty action commands is `git clone` with its "Cloning into | |
593 | '<path>'..." and "Checking connectivity..." status messages which it | |
594 | sends to the stderr stream. | |
595 | ||
596 | Error messages from Git commands should always be sent to the stderr | |
597 | stream. | |
598 | ||
599 | ||
0ae0e882 PO |
600 | Error Messages |
601 | ||
602 | - Do not end error messages with a full stop. | |
603 | ||
151b6c2d JH |
604 | - Do not capitalize the first word, only because it is the first word |
605 | in the message ("unable to open %s", not "Unable to open %s"). But | |
606 | "SHA-3 not supported" is fine, because the reason the first word is | |
607 | capitalized is not because it is at the beginning of the sentence, | |
608 | but because the word would be spelled in capital letters even when | |
609 | it appeared in the middle of the sentence. | |
0ae0e882 PO |
610 | |
611 | - Say what the error is first ("cannot open %s", not "%s: cannot open") | |
612 | ||
613 | ||
35840a3e JH |
614 | Externally Visible Names |
615 | ||
616 | - For configuration variable names, follow the existing convention: | |
617 | ||
618 | . The section name indicates the affected subsystem. | |
619 | ||
620 | . The subsection name, if any, indicates which of an unbounded set | |
621 | of things to set the value for. | |
622 | ||
623 | . The variable name describes the effect of tweaking this knob. | |
624 | ||
625 | The section and variable names that consist of multiple words are | |
e6397c5c | 626 | formed by concatenating the words without punctuation marks (e.g. `-`), |
35840a3e JH |
627 | and are broken using bumpyCaps in documentation as a hint to the |
628 | reader. | |
629 | ||
630 | When choosing the variable namespace, do not use variable name for | |
631 | specifying possibly unbounded set of things, most notably anything | |
632 | an end user can freely come up with (e.g. branch names). Instead, | |
633 | use subsection names or variable values, like the existing variable | |
634 | branch.<name>.description does. | |
635 | ||
636 | ||
c455bd89 ŠN |
637 | Writing Documentation: |
638 | ||
48bc1755 DW |
639 | Most (if not all) of the documentation pages are written in the |
640 | AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and | |
641 | processed into HTML and manpages (e.g. git.html and git.1 in the | |
642 | same directory). | |
bb9f2aec | 643 | |
42e0fae9 MB |
644 | The documentation liberally mixes US and UK English (en_US/UK) |
645 | norms for spelling and grammar, which is somewhat unfortunate. | |
646 | In an ideal world, it would have been better if it consistently | |
647 | used only one and not the other, and we would have picked en_US | |
648 | (if you wish to correct the English of some of the existing | |
649 | documentation, please see the documentation-related advice in the | |
650 | Documentation/SubmittingPatches file). | |
651 | ||
5b1cd37e JH |
652 | In order to ensure the documentation is inclusive, avoid assuming |
653 | that an unspecified example person is male or female, and think | |
654 | twice before using "he", "him", "she", or "her". Here are some | |
655 | tips to avoid use of gendered pronouns: | |
656 | ||
657 | - Prefer succinctness and matter-of-factly describing functionality | |
658 | in the abstract. E.g. | |
659 | ||
c42ea604 | 660 | `--short`:: Emit output in the short-format. |
5b1cd37e JH |
661 | |
662 | and avoid something like these overly verbose alternatives: | |
663 | ||
c42ea604 JNA |
664 | `--short`:: Use this to emit output in the short-format. |
665 | `--short`:: You can use this to get output in the short-format. | |
666 | `--short`:: A user who prefers shorter output could.... | |
667 | `--short`:: Should a person and/or program want shorter output, he | |
668 | she/they/it can... | |
5b1cd37e JH |
669 | |
670 | This practice often eliminates the need to involve human actors in | |
671 | your description, but it is a good practice regardless of the | |
672 | avoidance of gendered pronouns. | |
673 | ||
674 | - When it becomes awkward to stick to this style, prefer "you" when | |
c9dba103 | 675 | addressing the hypothetical user, and possibly "we" when |
5b1cd37e JH |
676 | discussing how the program might react to the user. E.g. |
677 | ||
c42ea604 | 678 | You can use this option instead of `--xyz`, but we might remove |
5b1cd37e JH |
679 | support for it in future versions. |
680 | ||
681 | while keeping in mind that you can probably be less verbose, e.g. | |
682 | ||
c42ea604 | 683 | Use this instead of `--xyz`. This option might be removed in future |
5b1cd37e JH |
684 | versions. |
685 | ||
686 | - If you still need to refer to an example person that is | |
687 | third-person singular, you may resort to "singular they" to avoid | |
688 | "he/she/him/her", e.g. | |
689 | ||
690 | A contributor asks their upstream to pull from them. | |
691 | ||
692 | Note that this sounds ungrammatical and unnatural to those who | |
693 | learned that "they" is only used for third-person plural, e.g. | |
694 | those who learn English as a second language in some parts of the | |
695 | world. | |
696 | ||
c455bd89 ŠN |
697 | Every user-visible change should be reflected in the documentation. |
698 | The same general rule as for code applies -- imitate the existing | |
ca03c368 JSJ |
699 | conventions. |
700 | ||
c455bd89 | 701 | |
c42ea604 JNA |
702 | Markup: |
703 | ||
704 | Literal parts (e.g. use of command-line options, command names, | |
705 | branch names, URLs, pathnames (files and directories), configuration and | |
706 | environment variables) must be typeset as verbatim (i.e. wrapped with | |
707 | backticks): | |
708 | `--pretty=oneline` | |
709 | `git rev-list` | |
710 | `remote.pushDefault` | |
711 | `http://git.example.com` | |
712 | `.git/config` | |
713 | `GIT_DIR` | |
714 | `HEAD` | |
715 | `umask`(2) | |
716 | ||
717 | An environment variable must be prefixed with "$" only when referring to its | |
718 | value and not when referring to the variable itself, in this case there is | |
719 | nothing to add except the backticks: | |
720 | `GIT_DIR` is specified | |
721 | `$GIT_DIR/hooks/pre-receive` | |
722 | ||
723 | Word phrases enclosed in `backtick characters` are rendered literally | |
724 | and will not be further expanded. The use of `backticks` to achieve the | |
725 | previous rule means that literal examples should not use AsciiDoc | |
726 | escapes. | |
727 | Correct: | |
728 | `--pretty=oneline` | |
729 | Incorrect: | |
730 | `\--pretty=oneline` | |
731 | ||
732 | Placeholders are spelled in lowercase and enclosed in | |
733 | angle brackets surrounded by underscores: | |
734 | _<file>_ | |
735 | _<commit>_ | |
c455bd89 | 736 | |
9c9b4f2f | 737 | If a placeholder has multiple words, they are separated by dashes: |
c42ea604 JNA |
738 | _<new-branch-name>_ |
739 | _<template-directory>_ | |
740 | ||
741 | A placeholder is not enclosed in backticks, as it is not a literal. | |
742 | ||
743 | When needed, use a distinctive identifier for placeholders, usually | |
744 | made of a qualification and a type: | |
745 | _<git-dir>_ | |
746 | _<key-id>_ | |
747 | ||
748 | When literal and placeholders are mixed, each markup is applied for | |
749 | each sub-entity. If they are stuck, a special markup, called | |
750 | unconstrained formatting is required. | |
751 | Unconstrained formating for placeholders is __<like-this>__ | |
752 | Unconstrained formatting for literal formatting is ++like this++ | |
753 | `--jobs` _<n>_ | |
754 | ++--sort=++__<key>__ | |
755 | __<directory>__++/.git++ | |
756 | ++remote.++__<name>__++.mirror++ | |
757 | ||
758 | caveat: ++ unconstrained format is not verbatim and may expand | |
759 | content. Use Asciidoc escapes inside them. | |
9c9b4f2f | 760 | |
c42ea604 JNA |
761 | Synopsis Syntax |
762 | ||
763 | Syntax grammar is formatted neither as literal nor as placeholder. | |
764 | ||
765 | A few commented examples follow to provide reference when writing or | |
766 | modifying command usage strings and synopsis sections in the manual | |
767 | pages: | |
0824639d | 768 | |
469bfc96 | 769 | Possibility of multiple occurrences is indicated by three dots: |
c42ea604 | 770 | _<file>_... |
c455bd89 ŠN |
771 | (One or more of <file>.) |
772 | ||
773 | Optional parts are enclosed in square brackets: | |
c42ea604 | 774 | [_<file>_...] |
6584fcc5 | 775 | (Zero or more of <file>.) |
c455bd89 | 776 | |
c42ea604 | 777 | ++--exec-path++[++=++__<path>__] |
c455bd89 ŠN |
778 | (Option with an optional argument. Note that the "=" is inside the |
779 | brackets.) | |
780 | ||
c42ea604 | 781 | [_<patch>_...] |
c455bd89 ŠN |
782 | (Zero or more of <patch>. Note that the dots are inside, not |
783 | outside the brackets.) | |
784 | ||
9c9b4f2f | 785 | Multiple alternatives are indicated with vertical bars: |
c42ea604 JNA |
786 | [`-q` | `--quiet`] |
787 | [`--utf8` | `--no-utf8`] | |
c455bd89 | 788 | |
6584fcc5 ÆAB |
789 | Use spacing around "|" token(s), but not immediately after opening or |
790 | before closing a [] or () pair: | |
c42ea604 JNA |
791 | Do: [`-q` | `--quiet`] |
792 | Don't: [`-q`|`--quiet`] | |
6584fcc5 | 793 | |
548afb0d | 794 | Don't use spacing around "|" tokens when they're used to separate the |
6584fcc5 | 795 | alternate arguments of an option: |
c42ea604 JNA |
796 | Do: ++--track++[++=++(`direct`|`inherit`)]` |
797 | Don't: ++--track++[++=++(`direct` | `inherit`)] | |
6584fcc5 | 798 | |
c455bd89 | 799 | Parentheses are used for grouping: |
c42ea604 | 800 | [(_<rev>_ | _<range>_)...] |
c455bd89 ŠN |
801 | (Any number of either <rev> or <range>. Parens are needed to make |
802 | it clear that "..." pertains to both <rev> and <range>.) | |
803 | ||
c42ea604 | 804 | [(`-p` _<parent>_)...] |
c455bd89 ŠN |
805 | (Any number of option -p, each with one <parent> argument.) |
806 | ||
c42ea604 | 807 | `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_) |
c455bd89 ŠN |
808 | (One and only one of "-a", "-d" or "<branch>" _must_ (no square |
809 | brackets) be provided.) | |
810 | ||
811 | And a somewhat more contrived example: | |
c42ea604 | 812 | `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]` |
c455bd89 ŠN |
813 | Here "=" is outside the brackets, because "--diff-filter=" is a |
814 | valid usage. "*" has its own pair of brackets, because it can | |
815 | (optionally) be specified only when one or more of the letters is | |
816 | also provided. | |
48a8c26c TA |
817 | |
818 | A note on notation: | |
819 | Use 'git' (all lowercase) when talking about commands i.e. something | |
820 | the user would type into a shell and use 'Git' (uppercase first letter) | |
821 | when talking about the version control system and its properties. | |
ca03c368 | 822 | |
ca03c368 JSJ |
823 | If some place in the documentation needs to typeset a command usage |
824 | example with inline substitutions, it is fine to use +monospaced and | |
825 | inline substituted text+ instead of `monospaced literal text`, and with | |
826 | the former, the part that should not get substituted must be | |
827 | quoted/escaped. |