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, a few 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."
interface translatable. See "Marking strings for translation" in
po/README.
+ - We do not write our "test" command with "-a" and "-o" and use "&&"
+ or "||" to concatenate multiple "test" commands instead, because
+ the use of "-a/-o" is often error-prone. E.g.
+
+ test -n "$x" -a "$a" = "$b"
+
+ is buggy and breaks when $x is "=", but
+
+ test -n "$x" && test "$a" = "$b"
+
+ does not have such a problem.
+
+
For C programs:
- We use tabs to indent, and interpret tabs as taking up to
Just do not mix styles in the same part of the code and mimic
existing styles in the neighbourhood.
+ - There are two schools of thought when it comes to splitting a long
+ logical line into multiple lines. Some people push the second and
+ subsequent lines far enough to the right with tabs and align them:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ while other people prefer to align the second and the subsequent
+ lines with the column immediately inside the opening parenthesis,
+ with tabs and spaces, following our "tabstop is always a multiple
+ of 8" convention:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ Both are valid, and we use both. Again, just do not mix styles in
+ the same part of the code and mimic existing styles in the
+ neighbourhood.
+
+ - When splitting a long logical line, some people change line before
+ a binary operator, so that the result looks like a parse tree when
+ you turn your head 90-degrees counterclockwise:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to
+ || span_more_than_a_single_line_of_the_source_text) {
+
+ while other people prefer to leave the operator at the end of the
+ line:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of_the_source_text) {
+
+ Both are valid, but we tend to use the latter more, unless the
+ expression gets fairly complex, in which case the former tends to
+ be easier to read. Again, just do not mix styles in the same part
+ of the code and mimic existing styles in the neighbourhood.
+
+ - When splitting a long logical line, with everything else being
+ equal, it is preferable to split after the operator at higher
+ level in the parse tree. That is, this is more preferable:
+
+ if (a_very_long_variable * that_is_used_in +
+ a_very_long_expression) {
+ ...
+
+ than
+
+ if (a_very_long_variable *
+ that_is_used_in + a_very_long_expression) {
+ ...
+
- Some clever tricks, like using the !! operator with arithmetic
constructs, can be extremely confusing to others. Avoid them,
unless there is a compelling reason to use them.
- When you come up with an API, document it.
- - The first #include in C files, except in platform specific
- compat/ implementations, should be git-compat-util.h or another
- header file that includes it, such as cache.h or builtin.h.
+ - The first #include in C files, except in platform specific compat/
+ implementations, must be either "git-compat-util.h", "cache.h" or
+ "builtin.h". You do not have to include more than one of these.
+
+ - A C file must directly include the header files that declare the
+ functions and the types it uses, except for the functions and types
+ that are made available to it by including one of the header files
+ it must include by the previous rule.
- If you are planning a new command, consider writing it in shell
or perl first, so that changes in semantics can be easily
documentation for version 2.6 does not mention this prefix, it has
been supported since version 2.6.0.
+Error Messages
+
+ - Do not end error messages with a full stop.
+
+ - Do not capitalize ("unable to open %s", not "Unable to open %s")
+
+ - Say what the error is first ("cannot open %s", not "%s: cannot open")
+
+
+Externally Visible Names
+
+ - For configuration variable names, follow the existing convention:
+
+ . The section name indicates the affected subsystem.
+
+ . The subsection name, if any, indicates which of an unbounded set
+ of things to set the value for.
+
+ . The variable name describes the effect of tweaking this knob.
+
+ The section and variable names that consist of multiple words are
+ formed by concatenating the words without punctuations (e.g. `-`),
+ and are broken using bumpyCaps in documentation as a hint to the
+ reader.
+
+ When choosing the variable namespace, do not use variable name for
+ specifying possibly unbounded set of things, most notably anything
+ an end user can freely come up with (e.g. branch names). Instead,
+ use subsection names or variable values, like the existing variable
+ branch.<name>.description does.
+
+
Writing Documentation:
Most (if not all) of the documentation pages are written in the
--sort=<key>
--abbrev[=<n>]
+ If a placeholder has multiple words, they are separated by dashes:
+ <new-branch-name>
+ --template=<template-directory>
+
Possibility of multiple occurrences is indicated by three dots:
<file>...
(One or more of <file>.)
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
- Multiple alternatives are indicated with vertical bar:
+ Multiple alternatives are indicated with vertical bars:
[-q | --quiet]
[--utf8 | --no-utf8]
Parentheses are used for grouping:
- [(<rev>|<range>)...]
+ [(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
`backticks around word phrases`, do so.
`--pretty=oneline`
`git rev-list`
- `remote.pushdefault`
+ `remote.pushDefault`
Word phrases enclosed in `backtick characters` are rendered literally
and will not be further expanded. The use of `backticks` to achieve the