1
1
Like other projects, we also have some guidelines to keep to the
2
code. For git in general, three rough rules are:
2
code. For Git in general, three rough rules are:
4
4
- Most importantly, we never say "It's in POSIX; we'll happily
5
5
ignore your needs should your system not conform to it."
18
18
judgement call, the decision based more on real world
19
19
constraints people face than what the paper standard says.
21
Make your code readable and sensible, and don't try to be clever.
22
23
As for more concrete guidelines, just imitate the existing code
23
24
(this is a good guideline, no matter which project you are
24
25
contributing to). It is always preferable to match the _local_
25
convention. New code added to git suite is expected to match
26
convention. New code added to Git suite is expected to match
26
27
the overall style of existing code. Modifications to existing
27
28
code is expected to match the style the surrounding code already
28
29
uses (even if it doesn't match the overall style of existing code).
77
78
- We do not use Process Substitution <(list) or >(list).
80
- Do not write control structures on a single line with semicolon.
81
"then" should be on the next line for if statements, and "do"
82
should be on the next line for "while" and "for".
79
84
- We prefer "test" over "[ ... ]".
81
86
- We do not write the noiseword "function" in front of shell
89
- We prefer a space between the function name and the parentheses. The
90
opening "{" should also be on the same line.
91
E.g.: my_function () {
84
93
- As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
85
94
[::], [==], nor [..]) for portability.
105
114
- We try to keep to at most 80 characters per line.
116
- We try to support a wide range of C compilers to compile Git with,
117
including old ones. That means that you should not use C99
118
initializers, even if a lot of compilers grok it.
120
- Variables have to be declared at the beginning of the block.
122
- NULL pointers shall be written as NULL, not as 0.
107
124
- When declaring pointers, the star sides with the variable
108
125
name, i.e. "char *string", not "char* string" or
109
126
"char * string". This makes it easier to understand code
149
166
- If you are planning a new command, consider writing it in shell
150
167
or perl first, so that changes in semantics can be easily
151
changed and discussed. Many git commands started out like
168
changed and discussed. Many Git commands started out like
152
169
that, and a few are still scripts.
154
- Avoid introducing a new dependency into git. This means you
171
- Avoid introducing a new dependency into Git. This means you
155
172
usually should stay away from scripting languages not already
156
used in the git core command set (unless your command is clearly
173
used in the Git core command set (unless your command is clearly
157
174
separate from it, such as an importer to convert random-scm-X
158
repositories to git).
175
repositories to Git).
160
177
- When we pass <string, length> pair to functions, we should try to
161
178
pass them in that order.
163
180
- Use Git's gettext wrappers to make the user interface
164
181
translatable. See "Marking strings for translation" in po/README.
185
- Most of the C guidelines above apply.
187
- We try to support Perl 5.8 and later ("use Perl 5.008").
189
- use strict and use warnings are strongly preferred.
191
- Don't overuse statement modifiers unless using them makes the
192
result easier to follow.
195
do_this() unless (condition);
196
... do something else ...
198
is more readable than:
204
... do something else ...
206
*only* when the condition is so rare that do_this() will be almost
209
- We try to avoid assignments inside "if ()" conditions.
211
- Learn and use Git.pm if you need that functionality.
213
- For Emacs, it's useful to put the following in
214
GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
216
;; note the first part is useful for C editing, too
217
((nil . ((indent-tabs-mode . t)
220
(cperl-mode . ((cperl-indent-level . 8)
221
(cperl-extra-newline-before-brace . nil)
222
(cperl-merge-trailing-else . t))))
226
- We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
228
- As a minimum, we aim to be compatible with Python 2.6 and 2.7.
230
- Where required libraries do not restrict us to Python 2, we try to
231
also be compatible with Python 3.1 and later.
233
- When you must differentiate between Unicode literals and byte string
234
literals, it is OK to use the 'b' prefix. Even though the Python
235
documentation for version 2.6 does not mention this prefix, it has
236
been supported since version 2.6.0.
166
238
Writing Documentation:
240
Most (if not all) of the documentation pages are written in the
241
AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
242
processed into HTML and manpages (e.g. git.html and git.1 in the
168
245
Every user-visible change should be reflected in the documentation.
169
246
The same general rule as for code applies -- imitate the existing
170
247
conventions. A few commented examples follow to provide reference
214
291
valid usage. "*" has its own pair of brackets, because it can
215
292
(optionally) be specified only when one or more of the letters is
296
Use 'git' (all lowercase) when talking about commands i.e. something
297
the user would type into a shell and use 'Git' (uppercase first letter)
298
when talking about the version control system and its properties.
added
removed
Documentation/CodingGuidelines
