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.
+
- 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.
+ - We use POSIX compliant parameter substitutions and avoid bashisms;
+ namely:
- - We use ${parameter#word} and its [#%] siblings, and their
- doubled "longest matching" form.
+ - We use ${parameter-word} and its [-=?+] siblings, and their
+ colon'ed "unset or null" form.
- - We use Arithmetic Expansion $(( ... )).
+ - 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 regexp ${parameter/pattern/string}.
+ - 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).
- Use the API. No, really. We have a strbuf (variable length
string), several arrays with the ALLOC_GROW() macro, a
- path_list for sorted string lists, a hash map (mapping struct
+ 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.
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.