]>
Commit | Line | Data |
---|---|---|
6d0618a8 JS |
1 | Like other projects, we also have some guidelines to keep to the |
2 | code. For git in general, three rough rules are: | |
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 | ||
21 | ||
22 | As for more concrete guidelines, just imitate the existing code | |
23 | (this is a good guideline, no matter which project you are | |
dfb047b9 NS |
24 | contributing to). It is always preferable to match the _local_ |
25 | convention. New code added to git suite is expected to match | |
26 | the overall style of existing code. Modifications to existing | |
27 | code is expected to match the style the surrounding code already | |
28 | uses (even if it doesn't match the overall style of existing code). | |
29 | ||
30 | But if you must have a list of rules, here they are. | |
6d0618a8 JS |
31 | |
32 | For shell scripts specifically (not exhaustive): | |
33 | ||
f36a4fa8 GB |
34 | - We use tabs for indentation. |
35 | ||
36 | - Case arms are indented at the same depth as case and esac lines. | |
37 | ||
48f359bf TH |
38 | - Redirection operators should be written with space before, but no |
39 | space after them. In other words, write 'echo test >"$file"' | |
40 | instead of 'echo test> $file' or 'echo test > $file'. Note that | |
41 | even though it is not required by POSIX to double-quote the | |
42 | redirection target in a variable (as shown above), our code does so | |
43 | because some versions of bash issue a warning without the quotes. | |
44 | ||
6d0618a8 JS |
45 | - We prefer $( ... ) for command substitution; unlike ``, it |
46 | properly nests. It should have been the way Bourne spelled | |
47 | it from day one, but unfortunately isn't. | |
48 | ||
860f70f9 TH |
49 | - If you want to find out if a command is available on the user's |
50 | $PATH, you should use 'type <command>', instead of 'which <command>'. | |
51 | The output of 'which' is not machine parseable and its exit code | |
52 | is not reliable across platforms. | |
53 | ||
bc979945 JH |
54 | - We use POSIX compliant parameter substitutions and avoid bashisms; |
55 | namely: | |
6d0618a8 | 56 | |
bc979945 JH |
57 | - We use ${parameter-word} and its [-=?+] siblings, and their |
58 | colon'ed "unset or null" form. | |
6d0618a8 | 59 | |
bc979945 JH |
60 | - We use ${parameter#word} and its [#%] siblings, and their |
61 | doubled "longest matching" form. | |
6d0618a8 | 62 | |
bc979945 | 63 | - No "Substring Expansion" ${parameter:offset:length}. |
055467dd | 64 | |
bc979945 | 65 | - No shell arrays. |
6d0618a8 | 66 | |
bc979945 | 67 | - No strlen ${#parameter}. |
6d0618a8 | 68 | |
bc979945 | 69 | - No pattern replacement ${parameter/pattern/string}. |
6d0618a8 | 70 | |
bc979945 JH |
71 | - We use Arithmetic Expansion $(( ... )). |
72 | ||
73 | - Inside Arithmetic Expansion, spell shell variables with $ in front | |
74 | of them, as some shells do not grok $((x)) while accepting $(($x)) | |
75 | just fine (e.g. dash older than 0.5.4). | |
6d0618a8 JS |
76 | |
77 | - We do not use Process Substitution <(list) or >(list). | |
78 | ||
03b05c7d HV |
79 | - Do not write control structures on a single line with semicolon. |
80 | "then" should be on the next line for if statements, and "do" | |
81 | should be on the next line for "while" and "for". | |
82 | ||
6d0618a8 JS |
83 | - We prefer "test" over "[ ... ]". |
84 | ||
85 | - We do not write the noiseword "function" in front of shell | |
86 | functions. | |
87 | ||
03b05c7d HV |
88 | - We prefer a space between the function name and the parentheses. The |
89 | opening "{" should also be on the same line. | |
90 | E.g.: my_function () { | |
91 | ||
009c98ee JH |
92 | - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, |
93 | [::], [==], nor [..]) for portability. | |
94 | ||
95 | - We do not use \{m,n\}; | |
96 | ||
97 | - We do not use -E; | |
98 | ||
99 | - We do not use ? nor + (which are \{0,1\} and \{1,\} | |
100 | respectively in BRE) but that goes without saying as these | |
101 | are ERE elements not BRE (note that \? and \+ are not even part | |
102 | of BRE -- making them accessible from BRE is a GNU extension). | |
103 | ||
5e9637c6 ÆAB |
104 | - Use Git's gettext wrappers in git-sh-i18n to make the user |
105 | interface translatable. See "Marking strings for translation" in | |
106 | po/README. | |
107 | ||
6d0618a8 JS |
108 | For C programs: |
109 | ||
110 | - We use tabs to indent, and interpret tabs as taking up to | |
111 | 8 spaces. | |
112 | ||
113 | - We try to keep to at most 80 characters per line. | |
114 | ||
a26fd033 AS |
115 | - We try to support a wide range of C compilers to compile git with, |
116 | including old ones. That means that you should not use C99 | |
117 | initializers, even if a lot of compilers grok it. | |
118 | ||
119 | - Variables have to be declared at the beginning of the block. | |
120 | ||
121 | - NULL pointers shall be written as NULL, not as 0. | |
122 | ||
6d0618a8 JS |
123 | - When declaring pointers, the star sides with the variable |
124 | name, i.e. "char *string", not "char* string" or | |
125 | "char * string". This makes it easier to understand code | |
126 | like "char *string, c;". | |
127 | ||
128 | - We avoid using braces unnecessarily. I.e. | |
129 | ||
130 | if (bla) { | |
131 | x = 1; | |
132 | } | |
133 | ||
134 | is frowned upon. A gray area is when the statement extends | |
135 | over a few lines, and/or you have a lengthy comment atop of | |
136 | it. Also, like in the Linux kernel, if there is a long list | |
137 | of "else if" statements, it can make sense to add braces to | |
138 | single line blocks. | |
139 | ||
0b0b8cd7 MV |
140 | - We try to avoid assignments inside if(). |
141 | ||
6d0618a8 JS |
142 | - Try to make your code understandable. You may put comments |
143 | in, but comments invariably tend to stale out when the code | |
144 | they were describing changes. Often splitting a function | |
145 | into two makes the intention of the code much clearer. | |
146 | ||
147 | - Double negation is often harder to understand than no negation | |
148 | at all. | |
149 | ||
150 | - Some clever tricks, like using the !! operator with arithmetic | |
151 | constructs, can be extremely confusing to others. Avoid them, | |
152 | unless there is a compelling reason to use them. | |
153 | ||
154 | - Use the API. No, really. We have a strbuf (variable length | |
155 | string), several arrays with the ALLOC_GROW() macro, a | |
c455c87c | 156 | string_list for sorted string lists, a hash map (mapping struct |
6d0618a8 JS |
157 | objects) named "struct decorate", amongst other things. |
158 | ||
159 | - When you come up with an API, document it. | |
160 | ||
161 | - The first #include in C files, except in platform specific | |
162 | compat/ implementations, should be git-compat-util.h or another | |
163 | header file that includes it, such as cache.h or builtin.h. | |
164 | ||
165 | - If you are planning a new command, consider writing it in shell | |
166 | or perl first, so that changes in semantics can be easily | |
167 | changed and discussed. Many git commands started out like | |
168 | that, and a few are still scripts. | |
169 | ||
170 | - Avoid introducing a new dependency into git. This means you | |
171 | usually should stay away from scripting languages not already | |
172 | used in the git core command set (unless your command is clearly | |
173 | separate from it, such as an importer to convert random-scm-X | |
174 | repositories to git). | |
57199892 KB |
175 | |
176 | - When we pass <string, length> pair to functions, we should try to | |
177 | pass them in that order. | |
c455bd89 | 178 | |
5e9637c6 ÆAB |
179 | - Use Git's gettext wrappers to make the user interface |
180 | translatable. See "Marking strings for translation" in po/README. | |
181 | ||
c455bd89 ŠN |
182 | Writing Documentation: |
183 | ||
184 | Every user-visible change should be reflected in the documentation. | |
185 | The same general rule as for code applies -- imitate the existing | |
186 | conventions. A few commented examples follow to provide reference | |
187 | when writing or modifying command usage strings and synopsis sections | |
188 | in the manual pages: | |
189 | ||
b1afe49d | 190 | Placeholders are spelled in lowercase and enclosed in angle brackets: |
c455bd89 ŠN |
191 | <file> |
192 | --sort=<key> | |
193 | --abbrev[=<n>] | |
194 | ||
469bfc96 | 195 | Possibility of multiple occurrences is indicated by three dots: |
c455bd89 ŠN |
196 | <file>... |
197 | (One or more of <file>.) | |
198 | ||
199 | Optional parts are enclosed in square brackets: | |
200 | [<extra>] | |
201 | (Zero or one <extra>.) | |
202 | ||
203 | --exec-path[=<path>] | |
204 | (Option with an optional argument. Note that the "=" is inside the | |
205 | brackets.) | |
206 | ||
207 | [<patch>...] | |
208 | (Zero or more of <patch>. Note that the dots are inside, not | |
209 | outside the brackets.) | |
210 | ||
211 | Multiple alternatives are indicated with vertical bar: | |
212 | [-q | --quiet] | |
213 | [--utf8 | --no-utf8] | |
214 | ||
215 | Parentheses are used for grouping: | |
216 | [(<rev>|<range>)...] | |
217 | (Any number of either <rev> or <range>. Parens are needed to make | |
218 | it clear that "..." pertains to both <rev> and <range>.) | |
219 | ||
220 | [(-p <parent>)...] | |
221 | (Any number of option -p, each with one <parent> argument.) | |
222 | ||
223 | git remote set-head <name> (-a | -d | <branch>) | |
224 | (One and only one of "-a", "-d" or "<branch>" _must_ (no square | |
225 | brackets) be provided.) | |
226 | ||
227 | And a somewhat more contrived example: | |
228 | --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] | |
229 | Here "=" is outside the brackets, because "--diff-filter=" is a | |
230 | valid usage. "*" has its own pair of brackets, because it can | |
231 | (optionally) be specified only when one or more of the letters is | |
232 | also provided. |