| Like other projects, we also have some guidelines to keep to the |
| 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." |
| We live in the real world. |
| |
| - However, we often say "Let's stay away from that construct, |
| it's not even in POSIX". |
| |
| - In spite of the above two rules, we sometimes say "Although |
| this is not in POSIX, it (is so convenient | makes the code |
| much more readable | has other good characteristics) and |
| practically all the platforms we care about support it, so |
| let's use it". |
| |
| Again, we live in the real world, and it is sometimes a |
| 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). 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. |
| |
| - 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 POSIX compliant parameter substitutions and avoid bashisms; |
| namely: |
| |
| - 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 shell arrays. |
| |
| - No strlen ${#parameter}. |
| |
| - No pattern replacement ${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. |
| |
| - We do not use \{m,n\}; |
| |
| - We do not use -E; |
| |
| - We do not use ? nor + (which are \{0,1\} and \{1,\} |
| respectively in BRE) but that goes without saying as these |
| 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 |
| 8 spaces. |
| |
| - 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 |
| like "char *string, c;". |
| |
| - We avoid using braces unnecessarily. I.e. |
| |
| if (bla) { |
| x = 1; |
| } |
| |
| is frowned upon. A gray area is when the statement extends |
| over a few lines, and/or you have a lengthy comment atop of |
| it. Also, like in the Linux kernel, if there is a long list |
| of "else if" statements, it can make sense to add braces to |
| single line blocks. |
| |
| - We try to avoid assignments inside if(). |
| |
| - Try to make your code understandable. You may put comments |
| in, but comments invariably tend to stale out when the code |
| they were describing changes. Often splitting a function |
| into two makes the intention of the code much clearer. |
| |
| - Double negation is often harder to understand than no negation |
| at all. |
| |
| - 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. |
| |
| - Use the API. No, really. We have a strbuf (variable length |
| string), several arrays with the ALLOC_GROW() macro, a |
| string_list for sorted string lists, a hash map (mapping struct |
| objects) named "struct decorate", amongst other things. |
| |
| - 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. |
| |
| - 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 |
| that, and a few are still scripts. |
| |
| - 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 |
| separate from it, such as an importer to convert random-scm-X |
| 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). |
| |
| 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. |