Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 1 | Like other projects, we also have some guidelines to keep to the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 2 | code. For Git in general, three rough rules are: |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 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 | |
Junio C Hamano | dd30800 | 2014-04-30 14:23:26 -0700 | [diff] [blame] | 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." |
| 27 | Cf. http://article.gmane.org/gmane.linux.kernel/943020 |
| 28 | |
Ted Zlatanov | c5e366b | 2013-02-06 14:49:01 -0500 | [diff] [blame] | 29 | Make your code readable and sensible, and don't try to be clever. |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 30 | |
| 31 | As for more concrete guidelines, just imitate the existing code |
| 32 | (this is a good guideline, no matter which project you are |
Nanako Shiraishi | dfb047b | 2009-01-26 17:32:22 +0900 | [diff] [blame] | 33 | contributing to). It is always preferable to match the _local_ |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 34 | convention. New code added to Git suite is expected to match |
Nanako Shiraishi | dfb047b | 2009-01-26 17:32:22 +0900 | [diff] [blame] | 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. |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 40 | |
| 41 | For shell scripts specifically (not exhaustive): |
| 42 | |
Giuseppe Bilotta | f36a4fa | 2010-12-03 17:47:35 +0100 | [diff] [blame] | 43 | - We use tabs for indentation. |
| 44 | |
Junio C Hamano | 79fc3ca | 2014-04-30 14:24:08 -0700 | [diff] [blame] | 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 |
Giuseppe Bilotta | f36a4fa | 2010-12-03 17:47:35 +0100 | [diff] [blame] | 56 | |
Tim Henigan | 48f359b | 2012-02-24 18:12:57 -0500 | [diff] [blame] | 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 | |
Junio C Hamano | 6a49909 | 2014-04-30 14:24:24 -0700 | [diff] [blame] | 64 | (incorrect) |
| 65 | cat hello > world < universe |
| 66 | echo hello >$world |
| 67 | |
| 68 | (correct) |
| 69 | cat hello >world <universe |
| 70 | echo hello >"$world" |
| 71 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 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 | |
Tim Henigan | 860f70f | 2012-02-24 18:12:58 -0500 | [diff] [blame] | 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>'. |
| 78 | The output of 'which' is not machine parseable and its exit code |
| 79 | is not reliable across platforms. |
| 80 | |
Junio C Hamano | bc97994 | 2010-10-13 11:15:14 -0700 | [diff] [blame] | 81 | - We use POSIX compliant parameter substitutions and avoid bashisms; |
| 82 | namely: |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 83 | |
Junio C Hamano | bc97994 | 2010-10-13 11:15:14 -0700 | [diff] [blame] | 84 | - We use ${parameter-word} and its [-=?+] siblings, and their |
| 85 | colon'ed "unset or null" form. |
| 86 | |
| 87 | - We use ${parameter#word} and its [#%] siblings, and their |
| 88 | doubled "longest matching" form. |
| 89 | |
| 90 | - No "Substring Expansion" ${parameter:offset:length}. |
| 91 | |
| 92 | - No shell arrays. |
| 93 | |
| 94 | - No strlen ${#parameter}. |
| 95 | |
| 96 | - No pattern replacement ${parameter/pattern/string}. |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 97 | |
| 98 | - We use Arithmetic Expansion $(( ... )). |
| 99 | |
Junio C Hamano | 055467d | 2010-09-22 12:15:37 -0700 | [diff] [blame] | 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). |
| 103 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 104 | - We do not use Process Substitution <(list) or >(list). |
| 105 | |
Heiko Voigt | 03b05c7 | 2012-08-15 19:06:01 +0200 | [diff] [blame] | 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 | |
Junio C Hamano | 9dbe780 | 2014-04-30 14:24:52 -0700 | [diff] [blame] | 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 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 121 | - We prefer "test" over "[ ... ]". |
| 122 | |
| 123 | - We do not write the noiseword "function" in front of shell |
| 124 | functions. |
| 125 | |
Junio C Hamano | 6117a3d | 2014-04-30 14:25:11 -0700 | [diff] [blame] | 126 | - We prefer a space between the function name and the parentheses, |
| 127 | and no space inside the parentheses. The opening "{" should also |
| 128 | be on the same line. |
| 129 | |
| 130 | (incorrect) |
| 131 | my_function(){ |
| 132 | ... |
| 133 | |
| 134 | (correct) |
| 135 | my_function () { |
| 136 | ... |
Heiko Voigt | 03b05c7 | 2012-08-15 19:06:01 +0200 | [diff] [blame] | 137 | |
Junio C Hamano | 009c98e | 2008-03-01 18:18:16 -0800 | [diff] [blame] | 138 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
Justin Lebar | a58088a | 2014-03-31 15:11:44 -0700 | [diff] [blame] | 139 | [::], [==], or [..]) for portability. |
Junio C Hamano | 009c98e | 2008-03-01 18:18:16 -0800 | [diff] [blame] | 140 | |
| 141 | - We do not use \{m,n\}; |
| 142 | |
| 143 | - We do not use -E; |
| 144 | |
Justin Lebar | a58088a | 2014-03-31 15:11:44 -0700 | [diff] [blame] | 145 | - We do not use ? or + (which are \{0,1\} and \{1,\} |
Junio C Hamano | 009c98e | 2008-03-01 18:18:16 -0800 | [diff] [blame] | 146 | respectively in BRE) but that goes without saying as these |
| 147 | are ERE elements not BRE (note that \? and \+ are not even part |
| 148 | of BRE -- making them accessible from BRE is a GNU extension). |
| 149 | |
Ævar Arnfjörð Bjarmason | 5e9637c | 2011-11-18 00:14:42 +0100 | [diff] [blame] | 150 | - Use Git's gettext wrappers in git-sh-i18n to make the user |
| 151 | interface translatable. See "Marking strings for translation" in |
| 152 | po/README. |
| 153 | |
Junio C Hamano | 897f964 | 2014-05-20 11:12:02 -0700 | [diff] [blame] | 154 | - We do not write our "test" command with "-a" and "-o" and use "&&" |
| 155 | or "||" to concatenate multiple "test" commands instead, because |
| 156 | the use of "-a/-o" is often error-prone. E.g. |
| 157 | |
| 158 | test -n "$x" -a "$a" = "$b" |
| 159 | |
| 160 | is buggy and breaks when $x is "=", but |
| 161 | |
| 162 | test -n "$x" && test "$a" = "$b" |
| 163 | |
| 164 | does not have such a problem. |
| 165 | |
| 166 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 167 | For C programs: |
| 168 | |
| 169 | - We use tabs to indent, and interpret tabs as taking up to |
| 170 | 8 spaces. |
| 171 | |
| 172 | - We try to keep to at most 80 characters per line. |
| 173 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 174 | - We try to support a wide range of C compilers to compile Git with, |
Adam Spiers | a26fd03 | 2012-12-16 19:36:00 +0000 | [diff] [blame] | 175 | including old ones. That means that you should not use C99 |
| 176 | initializers, even if a lot of compilers grok it. |
| 177 | |
| 178 | - Variables have to be declared at the beginning of the block. |
| 179 | |
| 180 | - NULL pointers shall be written as NULL, not as 0. |
| 181 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 182 | - When declaring pointers, the star sides with the variable |
| 183 | name, i.e. "char *string", not "char* string" or |
| 184 | "char * string". This makes it easier to understand code |
| 185 | like "char *string, c;". |
| 186 | |
Jeff King | f57b6cf | 2014-02-28 01:17:25 -0500 | [diff] [blame] | 187 | - Use whitespace around operators and keywords, but not inside |
| 188 | parentheses and not around functions. So: |
| 189 | |
| 190 | while (condition) |
| 191 | func(bar + 1); |
| 192 | |
| 193 | and not: |
| 194 | |
| 195 | while( condition ) |
| 196 | func (bar+1); |
| 197 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 198 | - We avoid using braces unnecessarily. I.e. |
| 199 | |
| 200 | if (bla) { |
| 201 | x = 1; |
| 202 | } |
| 203 | |
| 204 | is frowned upon. A gray area is when the statement extends |
| 205 | over a few lines, and/or you have a lengthy comment atop of |
| 206 | it. Also, like in the Linux kernel, if there is a long list |
| 207 | of "else if" statements, it can make sense to add braces to |
| 208 | single line blocks. |
| 209 | |
Junio C Hamano | 691d0dd | 2014-04-30 14:25:47 -0700 | [diff] [blame] | 210 | - We try to avoid assignments in the condition of an "if" statement. |
Miklos Vajna | 0b0b8cd | 2008-05-23 01:26:09 +0200 | [diff] [blame] | 211 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 212 | - Try to make your code understandable. You may put comments |
| 213 | in, but comments invariably tend to stale out when the code |
| 214 | they were describing changes. Often splitting a function |
| 215 | into two makes the intention of the code much clearer. |
| 216 | |
brian m. carlson | b75a6ca | 2013-10-12 00:45:46 +0000 | [diff] [blame] | 217 | - Multi-line comments include their delimiters on separate lines from |
| 218 | the text. E.g. |
| 219 | |
| 220 | /* |
| 221 | * A very long |
| 222 | * multi-line comment. |
| 223 | */ |
| 224 | |
Junio C Hamano | cbcfd4e | 2014-04-18 10:48:08 -0700 | [diff] [blame] | 225 | Note however that a comment that explains a translatable string to |
| 226 | translators uses a convention of starting with a magic token |
| 227 | "TRANSLATORS: " immediately after the opening delimiter, even when |
| 228 | it spans multiple lines. We do not add an asterisk at the beginning |
| 229 | of each line, either. E.g. |
| 230 | |
| 231 | /* TRANSLATORS: here is a comment that explains the string |
| 232 | to be translated, that follows immediately after it */ |
| 233 | _("Here is a translatable string explained by the above."); |
| 234 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 235 | - Double negation is often harder to understand than no negation |
| 236 | at all. |
| 237 | |
Junio C Hamano | 5db9ab8 | 2014-04-30 14:26:23 -0700 | [diff] [blame] | 238 | - There are two schools of thought when it comes to comparison, |
| 239 | especially inside a loop. Some people prefer to have the less stable |
| 240 | value on the left hand side and the more stable value on the right hand |
| 241 | side, e.g. if you have a loop that counts variable i down to the |
| 242 | lower bound, |
| 243 | |
| 244 | while (i > lower_bound) { |
| 245 | do something; |
| 246 | i--; |
| 247 | } |
| 248 | |
| 249 | Other people prefer to have the textual order of values match the |
| 250 | actual order of values in their comparison, so that they can |
| 251 | mentally draw a number line from left to right and place these |
| 252 | values in order, i.e. |
| 253 | |
| 254 | while (lower_bound < i) { |
| 255 | do something; |
| 256 | i--; |
| 257 | } |
| 258 | |
| 259 | Both are valid, and we use both. However, the more "stable" the |
| 260 | stable side becomes, the more we tend to prefer the former |
| 261 | (comparison with a constant, "i > 0", is an extreme example). |
| 262 | Just do not mix styles in the same part of the code and mimic |
| 263 | existing styles in the neighbourhood. |
| 264 | |
Junio C Hamano | f26443d | 2014-05-02 13:42:39 -0700 | [diff] [blame] | 265 | - There are two schools of thought when it comes to splitting a long |
| 266 | logical line into multiple lines. Some people push the second and |
| 267 | subsequent lines far enough to the right with tabs and align them: |
| 268 | |
| 269 | if (the_beginning_of_a_very_long_expression_that_has_to || |
| 270 | span_more_than_a_single_line_of || |
| 271 | the_source_text) { |
| 272 | ... |
| 273 | |
| 274 | while other people prefer to align the second and the subsequent |
| 275 | lines with the column immediately inside the opening parenthesis, |
| 276 | with tabs and spaces, following our "tabstop is always a multiple |
| 277 | of 8" convention: |
| 278 | |
| 279 | if (the_beginning_of_a_very_long_expression_that_has_to || |
| 280 | span_more_than_a_single_line_of || |
| 281 | the_source_text) { |
| 282 | ... |
| 283 | |
| 284 | Both are valid, and we use both. Again, just do not mix styles in |
| 285 | the same part of the code and mimic existing styles in the |
| 286 | neighbourhood. |
| 287 | |
| 288 | - When splitting a long logical line, some people change line before |
| 289 | a binary operator, so that the result looks like a parse tree when |
| 290 | you turn your head 90-degrees counterclockwise: |
| 291 | |
| 292 | if (the_beginning_of_a_very_long_expression_that_has_to |
| 293 | || span_more_than_a_single_line_of_the_source_text) { |
| 294 | |
| 295 | while other people prefer to leave the operator at the end of the |
| 296 | line: |
| 297 | |
| 298 | if (the_beginning_of_a_very_long_expression_that_has_to || |
| 299 | span_more_than_a_single_line_of_the_source_text) { |
| 300 | |
| 301 | Both are valid, but we tend to use the latter more, unless the |
| 302 | expression gets fairly complex, in which case the former tends to |
| 303 | be easier to read. Again, just do not mix styles in the same part |
| 304 | of the code and mimic existing styles in the neighbourhood. |
| 305 | |
| 306 | - When splitting a long logical line, with everything else being |
| 307 | equal, it is preferable to split after the operator at higher |
| 308 | level in the parse tree. That is, this is more preferable: |
| 309 | |
| 310 | if (a_very_long_variable * that_is_used_in + |
| 311 | a_very_long_expression) { |
| 312 | ... |
| 313 | |
| 314 | than |
| 315 | |
| 316 | if (a_very_long_variable * |
| 317 | that_is_used_in + a_very_long_expression) { |
| 318 | ... |
| 319 | |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 320 | - Some clever tricks, like using the !! operator with arithmetic |
| 321 | constructs, can be extremely confusing to others. Avoid them, |
| 322 | unless there is a compelling reason to use them. |
| 323 | |
| 324 | - Use the API. No, really. We have a strbuf (variable length |
| 325 | string), several arrays with the ALLOC_GROW() macro, a |
Johannes Schindelin | c455c87 | 2008-07-21 19:03:49 +0100 | [diff] [blame] | 326 | string_list for sorted string lists, a hash map (mapping struct |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 327 | objects) named "struct decorate", amongst other things. |
| 328 | |
| 329 | - When you come up with an API, document it. |
| 330 | |
Junio C Hamano | 412cb2e | 2015-01-15 15:20:09 -0800 | [diff] [blame] | 331 | - The first #include in C files, except in platform specific compat/ |
| 332 | implementations, must be either "git-compat-util.h", "cache.h" or |
| 333 | "builtin.h". You do not have to include more than one of these. |
| 334 | |
| 335 | - A C file must directly include the header files that declare the |
| 336 | functions and the types it uses, except for the functions and types |
| 337 | that are made available to it by including one of the header files |
| 338 | it must include by the previous rule. |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 339 | |
| 340 | - If you are planning a new command, consider writing it in shell |
| 341 | or perl first, so that changes in semantics can be easily |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 342 | changed and discussed. Many Git commands started out like |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 343 | that, and a few are still scripts. |
| 344 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 345 | - Avoid introducing a new dependency into Git. This means you |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 346 | usually should stay away from scripting languages not already |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 347 | used in the Git core command set (unless your command is clearly |
Johannes Schindelin | 6d0618a | 2007-11-08 00:33:19 +0000 | [diff] [blame] | 348 | separate from it, such as an importer to convert random-scm-X |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 349 | repositories to Git). |
Kjetil Barvik | 5719989 | 2009-02-09 21:54:06 +0100 | [diff] [blame] | 350 | |
| 351 | - When we pass <string, length> pair to functions, we should try to |
| 352 | pass them in that order. |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 353 | |
Ævar Arnfjörð Bjarmason | 5e9637c | 2011-11-18 00:14:42 +0100 | [diff] [blame] | 354 | - Use Git's gettext wrappers to make the user interface |
| 355 | translatable. See "Marking strings for translation" in po/README. |
| 356 | |
Ted Zlatanov | c5e366b | 2013-02-06 14:49:01 -0500 | [diff] [blame] | 357 | For Perl programs: |
| 358 | |
| 359 | - Most of the C guidelines above apply. |
| 360 | |
| 361 | - We try to support Perl 5.8 and later ("use Perl 5.008"). |
| 362 | |
| 363 | - use strict and use warnings are strongly preferred. |
| 364 | |
| 365 | - Don't overuse statement modifiers unless using them makes the |
| 366 | result easier to follow. |
| 367 | |
| 368 | ... do something ... |
| 369 | do_this() unless (condition); |
| 370 | ... do something else ... |
| 371 | |
| 372 | is more readable than: |
| 373 | |
| 374 | ... do something ... |
| 375 | unless (condition) { |
| 376 | do_this(); |
| 377 | } |
| 378 | ... do something else ... |
| 379 | |
| 380 | *only* when the condition is so rare that do_this() will be almost |
| 381 | always called. |
| 382 | |
| 383 | - We try to avoid assignments inside "if ()" conditions. |
| 384 | |
| 385 | - Learn and use Git.pm if you need that functionality. |
| 386 | |
| 387 | - For Emacs, it's useful to put the following in |
| 388 | GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: |
| 389 | |
| 390 | ;; note the first part is useful for C editing, too |
| 391 | ((nil . ((indent-tabs-mode . t) |
| 392 | (tab-width . 8) |
| 393 | (fill-column . 80))) |
| 394 | (cperl-mode . ((cperl-indent-level . 8) |
| 395 | (cperl-extra-newline-before-brace . nil) |
| 396 | (cperl-merge-trailing-else . t)))) |
| 397 | |
John Keeping | 9ef43dd | 2013-01-30 20:47:32 +0000 | [diff] [blame] | 398 | For Python scripts: |
| 399 | |
| 400 | - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). |
| 401 | |
| 402 | - As a minimum, we aim to be compatible with Python 2.6 and 2.7. |
| 403 | |
| 404 | - Where required libraries do not restrict us to Python 2, we try to |
| 405 | also be compatible with Python 3.1 and later. |
| 406 | |
| 407 | - When you must differentiate between Unicode literals and byte string |
| 408 | literals, it is OK to use the 'b' prefix. Even though the Python |
| 409 | documentation for version 2.6 does not mention this prefix, it has |
| 410 | been supported since version 2.6.0. |
| 411 | |
Philip Oakley | 0ae0e88 | 2014-06-16 13:55:57 +0100 | [diff] [blame] | 412 | Error Messages |
| 413 | |
| 414 | - Do not end error messages with a full stop. |
| 415 | |
| 416 | - Do not capitalize ("unable to open %s", not "Unable to open %s") |
| 417 | |
| 418 | - Say what the error is first ("cannot open %s", not "%s: cannot open") |
| 419 | |
| 420 | |
Junio C Hamano | 35840a3 | 2015-01-27 12:26:03 -0800 | [diff] [blame] | 421 | Externally Visible Names |
| 422 | |
| 423 | - For configuration variable names, follow the existing convention: |
| 424 | |
| 425 | . The section name indicates the affected subsystem. |
| 426 | |
| 427 | . The subsection name, if any, indicates which of an unbounded set |
| 428 | of things to set the value for. |
| 429 | |
| 430 | . The variable name describes the effect of tweaking this knob. |
| 431 | |
| 432 | The section and variable names that consist of multiple words are |
| 433 | formed by concatenating the words without punctuations (e.g. `-`), |
| 434 | and are broken using bumpyCaps in documentation as a hint to the |
| 435 | reader. |
| 436 | |
| 437 | When choosing the variable namespace, do not use variable name for |
| 438 | specifying possibly unbounded set of things, most notably anything |
| 439 | an end user can freely come up with (e.g. branch names). Instead, |
| 440 | use subsection names or variable values, like the existing variable |
| 441 | branch.<name>.description does. |
| 442 | |
| 443 | |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 444 | Writing Documentation: |
| 445 | |
Dale Worley | 48bc175 | 2013-05-07 13:39:46 -0400 | [diff] [blame] | 446 | Most (if not all) of the documentation pages are written in the |
| 447 | AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and |
| 448 | processed into HTML and manpages (e.g. git.html and git.1 in the |
| 449 | same directory). |
Junio C Hamano | bb9f2ae | 2013-03-21 14:17:32 -0700 | [diff] [blame] | 450 | |
Marc Branchaud | 42e0fae | 2013-08-01 14:49:54 -0400 | [diff] [blame] | 451 | The documentation liberally mixes US and UK English (en_US/UK) |
| 452 | norms for spelling and grammar, which is somewhat unfortunate. |
| 453 | In an ideal world, it would have been better if it consistently |
| 454 | used only one and not the other, and we would have picked en_US |
| 455 | (if you wish to correct the English of some of the existing |
| 456 | documentation, please see the documentation-related advice in the |
| 457 | Documentation/SubmittingPatches file). |
| 458 | |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 459 | Every user-visible change should be reflected in the documentation. |
| 460 | The same general rule as for code applies -- imitate the existing |
Jason St. John | ca03c36 | 2013-11-14 18:08:45 -0500 | [diff] [blame] | 461 | conventions. |
| 462 | |
| 463 | A few commented examples follow to provide reference when writing or |
| 464 | modifying command usage strings and synopsis sections in the manual |
| 465 | pages: |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 466 | |
Junio C Hamano | b1afe49 | 2011-02-15 11:02:56 -0800 | [diff] [blame] | 467 | Placeholders are spelled in lowercase and enclosed in angle brackets: |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 468 | <file> |
| 469 | --sort=<key> |
| 470 | --abbrev[=<n>] |
| 471 | |
Alex Henrie | 9c9b4f2 | 2015-01-13 00:44:47 -0700 | [diff] [blame] | 472 | If a placeholder has multiple words, they are separated by dashes: |
| 473 | <new-branch-name> |
| 474 | --template=<template-directory> |
| 475 | |
Ralf Wildenhues | 469bfc9 | 2011-01-03 20:03:34 +0100 | [diff] [blame] | 476 | Possibility of multiple occurrences is indicated by three dots: |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 477 | <file>... |
| 478 | (One or more of <file>.) |
| 479 | |
| 480 | Optional parts are enclosed in square brackets: |
| 481 | [<extra>] |
| 482 | (Zero or one <extra>.) |
| 483 | |
| 484 | --exec-path[=<path>] |
| 485 | (Option with an optional argument. Note that the "=" is inside the |
| 486 | brackets.) |
| 487 | |
| 488 | [<patch>...] |
| 489 | (Zero or more of <patch>. Note that the dots are inside, not |
| 490 | outside the brackets.) |
| 491 | |
Alex Henrie | 9c9b4f2 | 2015-01-13 00:44:47 -0700 | [diff] [blame] | 492 | Multiple alternatives are indicated with vertical bars: |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 493 | [-q | --quiet] |
| 494 | [--utf8 | --no-utf8] |
| 495 | |
| 496 | Parentheses are used for grouping: |
Alex Henrie | 9c9b4f2 | 2015-01-13 00:44:47 -0700 | [diff] [blame] | 497 | [(<rev> | <range>)...] |
Štěpán Němec | c455bd8 | 2010-11-04 18:12:48 +0100 | [diff] [blame] | 498 | (Any number of either <rev> or <range>. Parens are needed to make |
| 499 | it clear that "..." pertains to both <rev> and <range>.) |
| 500 | |
| 501 | [(-p <parent>)...] |
| 502 | (Any number of option -p, each with one <parent> argument.) |
| 503 | |
| 504 | git remote set-head <name> (-a | -d | <branch>) |
| 505 | (One and only one of "-a", "-d" or "<branch>" _must_ (no square |
| 506 | brackets) be provided.) |
| 507 | |
| 508 | And a somewhat more contrived example: |
| 509 | --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] |
| 510 | Here "=" is outside the brackets, because "--diff-filter=" is a |
| 511 | valid usage. "*" has its own pair of brackets, because it can |
| 512 | (optionally) be specified only when one or more of the letters is |
| 513 | also provided. |
Thomas Ackermann | 48a8c26 | 2013-01-21 20:16:20 +0100 | [diff] [blame] | 514 | |
| 515 | A note on notation: |
| 516 | Use 'git' (all lowercase) when talking about commands i.e. something |
| 517 | the user would type into a shell and use 'Git' (uppercase first letter) |
| 518 | when talking about the version control system and its properties. |
Jason St. John | ca03c36 | 2013-11-14 18:08:45 -0500 | [diff] [blame] | 519 | |
| 520 | A few commented examples follow to provide reference when writing or |
| 521 | modifying paragraphs or option/command explanations that contain options |
| 522 | or commands: |
| 523 | |
| 524 | Literal examples (e.g. use of command-line options, command names, and |
| 525 | configuration variables) are typeset in monospace, and if you can use |
| 526 | `backticks around word phrases`, do so. |
| 527 | `--pretty=oneline` |
| 528 | `git rev-list` |
Nguyễn Thái Ngọc Duy | da0005b | 2015-03-11 16:32:45 -0400 | [diff] [blame^] | 529 | `remote.pushDefault` |
Jason St. John | ca03c36 | 2013-11-14 18:08:45 -0500 | [diff] [blame] | 530 | |
| 531 | Word phrases enclosed in `backtick characters` are rendered literally |
| 532 | and will not be further expanded. The use of `backticks` to achieve the |
| 533 | previous rule means that literal examples should not use AsciiDoc |
| 534 | escapes. |
| 535 | Correct: |
| 536 | `--pretty=oneline` |
| 537 | Incorrect: |
| 538 | `\--pretty=oneline` |
| 539 | |
| 540 | If some place in the documentation needs to typeset a command usage |
| 541 | example with inline substitutions, it is fine to use +monospaced and |
| 542 | inline substituted text+ instead of `monospaced literal text`, and with |
| 543 | the former, the part that should not get substituted must be |
| 544 | quoted/escaped. |