Like other projects, we also have some guidelines to keep to the
-code. For git in general, three rough rules are:
+code. For Git in general, three rough rules are:
- Most importantly, we never say "It's in POSIX; we'll happily
ignore your needs should your system not conform to it."
judgement call, the decision based more on real world
constraints people face than what the paper standard says.
+Make your code readable and sensible, and don't try to be clever.
As for more concrete guidelines, just imitate the existing code
(this is a good guideline, no matter which project you are
-contributing to). But if you must have a list of rules,
-here they are.
+contributing to). It is always preferable to match the _local_
+convention. New code added to Git suite is expected to match
+the overall style of existing code. Modifications to existing
+code is expected to match the style the surrounding code already
+uses (even if it doesn't match the overall style of existing code).
+
+But if you must have a list of rules, here they are.
For shell scripts specifically (not exhaustive):
+ - We use tabs for indentation.
+
+ - Case arms are indented at the same depth as case and esac lines.
+
+ - Redirection operators should be written with space before, but no
+ space after them. In other words, write 'echo test >"$file"'
+ instead of 'echo test> $file' or 'echo test > $file'. Note that
+ even though it is not required by POSIX to double-quote the
+ redirection target in a variable (as shown above), our code does so
+ because some versions of bash issue a warning without the quotes.
+
- We prefer $( ... ) for command substitution; unlike ``, it
properly nests. It should have been the way Bourne spelled
it from day one, but unfortunately isn't.
- - We use ${parameter-word} and its [-=?+] siblings, and their
- colon'ed "unset or null" form.
+ - If you want to find out if a command is available on the user's
+ $PATH, you should use 'type <command>', instead of 'which <command>'.
+ The output of 'which' is not machine parseable and its exit code
+ is not reliable across platforms.
- - We use ${parameter#word} and its [#%] siblings, and their
- doubled "longest matching" form.
+ - We use POSIX compliant parameter substitutions and avoid bashisms;
+ namely:
- - We use Arithmetic Expansion $(( ... )).
+ - We use ${parameter-word} and its [-=?+] siblings, and their
+ colon'ed "unset or null" form.
+
+ - We use ${parameter#word} and its [#%] siblings, and their
+ doubled "longest matching" form.
+
+ - No "Substring Expansion" ${parameter:offset:length}.
- - No "Substring Expansion" ${parameter:offset:length}.
+ - No shell arrays.
- - No shell arrays.
+ - No strlen ${#parameter}.
- - No strlen ${#parameter}.
+ - No pattern replacement ${parameter/pattern/string}.
- - No regexp ${parameter/pattern/string}.
+ - We use Arithmetic Expansion $(( ... )).
+
+ - Inside Arithmetic Expansion, spell shell variables with $ in front
+ of them, as some shells do not grok $((x)) while accepting $(($x))
+ just fine (e.g. dash older than 0.5.4).
- We do not use Process Substitution <(list) or >(list).
+ - Do not write control structures on a single line with semicolon.
+ "then" should be on the next line for if statements, and "do"
+ should be on the next line for "while" and "for".
+
- We prefer "test" over "[ ... ]".
- We do not write the noiseword "function" in front of shell
functions.
+ - We prefer a space between the function name and the parentheses. The
+ opening "{" should also be on the same line.
+ E.g.: my_function () {
+
- As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
[::], [==], nor [..]) for portability.
are ERE elements not BRE (note that \? and \+ are not even part
of BRE -- making them accessible from BRE is a GNU extension).
+ - Use Git's gettext wrappers in git-sh-i18n to make the user
+ interface translatable. See "Marking strings for translation" in
+ po/README.
+
For C programs:
- We use tabs to indent, and interpret tabs as taking up to
- We try to keep to at most 80 characters per line.
+ - We try to support a wide range of C compilers to compile Git with,
+ including old ones. That means that you should not use C99
+ initializers, even if a lot of compilers grok it.
+
+ - Variables have to be declared at the beginning of the block.
+
+ - NULL pointers shall be written as NULL, not as 0.
+
- When declaring pointers, the star sides with the variable
name, i.e. "char *string", not "char* string" or
"char * string". This makes it easier to understand code
they were describing changes. Often splitting a function
into two makes the intention of the code much clearer.
+ - Multi-line comments include their delimiters on separate lines from
+ the text. E.g.
+
+ /*
+ * A very long
+ * multi-line comment.
+ */
+
- Double negation is often harder to understand than no negation
at all.
- If you are planning a new command, consider writing it in shell
or perl first, so that changes in semantics can be easily
- changed and discussed. Many git commands started out like
+ changed and discussed. Many Git commands started out like
that, and a few are still scripts.
- - Avoid introducing a new dependency into git. This means you
+ - Avoid introducing a new dependency into Git. This means you
usually should stay away from scripting languages not already
- used in the git core command set (unless your command is clearly
+ used in the Git core command set (unless your command is clearly
separate from it, such as an importer to convert random-scm-X
- repositories to git).
+ repositories to Git).
+
+ - When we pass <string, length> pair to functions, we should try to
+ pass them in that order.
+
+ - Use Git's gettext wrappers to make the user interface
+ translatable. See "Marking strings for translation" in po/README.
+
+For Perl programs:
+
+ - Most of the C guidelines above apply.
+
+ - We try to support Perl 5.8 and later ("use Perl 5.008").
+
+ - use strict and use warnings are strongly preferred.
+
+ - Don't overuse statement modifiers unless using them makes the
+ result easier to follow.
+
+ ... do something ...
+ do_this() unless (condition);
+ ... do something else ...
+
+ is more readable than:
+
+ ... do something ...
+ unless (condition) {
+ do_this();
+ }
+ ... do something else ...
+
+ *only* when the condition is so rare that do_this() will be almost
+ always called.
+
+ - We try to avoid assignments inside "if ()" conditions.
+
+ - Learn and use Git.pm if you need that functionality.
+
+ - For Emacs, it's useful to put the following in
+ GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
+
+ ;; note the first part is useful for C editing, too
+ ((nil . ((indent-tabs-mode . t)
+ (tab-width . 8)
+ (fill-column . 80)))
+ (cperl-mode . ((cperl-indent-level . 8)
+ (cperl-extra-newline-before-brace . nil)
+ (cperl-merge-trailing-else . t))))
+
+For Python scripts:
+
+ - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
+
+ - As a minimum, we aim to be compatible with Python 2.6 and 2.7.
+
+ - Where required libraries do not restrict us to Python 2, we try to
+ also be compatible with Python 3.1 and later.
+
+ - When you must differentiate between Unicode literals and byte string
+ literals, it is OK to use the 'b' prefix. Even though the Python
+ documentation for version 2.6 does not mention this prefix, it has
+ been supported since version 2.6.0.
+
+Writing Documentation:
+
+ Most (if not all) of the documentation pages are written in the
+ AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
+ processed into HTML and manpages (e.g. git.html and git.1 in the
+ same directory).
+
+ The documentation liberally mixes US and UK English (en_US/UK)
+ norms for spelling and grammar, which is somewhat unfortunate.
+ In an ideal world, it would have been better if it consistently
+ used only one and not the other, and we would have picked en_US
+ (if you wish to correct the English of some of the existing
+ documentation, please see the documentation-related advice in the
+ Documentation/SubmittingPatches file).
+
+ Every user-visible change should be reflected in the documentation.
+ The same general rule as for code applies -- imitate the existing
+ conventions. A few commented examples follow to provide reference
+ when writing or modifying command usage strings and synopsis sections
+ in the manual pages:
+
+ Placeholders are spelled in lowercase and enclosed in angle brackets:
+ <file>
+ --sort=<key>
+ --abbrev[=<n>]
+
+ Possibility of multiple occurrences is indicated by three dots:
+ <file>...
+ (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+ [<extra>]
+ (Zero or one <extra>.)
+
+ --exec-path[=<path>]
+ (Option with an optional argument. Note that the "=" is inside the
+ brackets.)
+
+ [<patch>...]
+ (Zero or more of <patch>. Note that the dots are inside, not
+ outside the brackets.)
+
+ Multiple alternatives are indicated with vertical bar:
+ [-q | --quiet]
+ [--utf8 | --no-utf8]
+
+ Parentheses are used for grouping:
+ [(<rev>|<range>)...]
+ (Any number of either <rev> or <range>. Parens are needed to make
+ it clear that "..." pertains to both <rev> and <range>.)
+
+ [(-p <parent>)...]
+ (Any number of option -p, each with one <parent> argument.)
+
+ git remote set-head <name> (-a | -d | <branch>)
+ (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+ brackets) be provided.)
+
+ And a somewhat more contrived example:
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
+ Here "=" is outside the brackets, because "--diff-filter=" is a
+ valid usage. "*" has its own pair of brackets, because it can
+ (optionally) be specified only when one or more of the letters is
+ also provided.
+
+ A note on notation:
+ Use 'git' (all lowercase) when talking about commands i.e. something
+ the user would type into a shell and use 'Git' (uppercase first letter)
+ when talking about the version control system and its properties.