Merge remote-tracking branch 'ko/maint' into jc/diff-index-quick-exit-early

* ko/maint: (4352 commits)
  git-submodule.sh: separate parens by a space to avoid confusing some shells
  Documentation/technical/api-diff.txt: correct name of diff_unmerge()
  read_gitfile_gently: use ssize_t to hold read result
  remove tests of always-false condition
  rerere.c: diagnose a corrupt MERGE_RR when hitting EOF between TAB and '\0'
  Git 1.7.5.3
  init/clone: remove short option -L and document --separate-git-dir
  do not read beyond end of malloc'd buffer
  git-svn: Fix git svn log --show-commit
  Git 1.7.5.2
  provide a copy of the LGPLv2.1
  test core.gitproxy configuration
  copy_gecos: fix not adding nlen to len when processing "&"
  Update draft release notes to 1.7.5.2
  Documentation/git-fsck.txt: fix typo: unreadable -> unreachable
  send-pack: avoid deadlock on git:// push with failed pack-objects
  connect: let callers know if connection is a socket
  connect: treat generic proxy processes like ssh processes
  sideband_demux(): fix decl-after-stmt
  t3503: test cherry picking and reverting root commits
  ...

Conflicts:
	diff.c

1 files changed, 72 insertions, 9 deletions

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index b8bf618a30..fe1c1e5bc2 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -31,25 +31,36 @@ 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).
 
@@ -132,3 +143,55 @@ For C programs:
 
  - When we pass <string, length> pair to functions, we should try to
    pass them in that order.
+
+Writing Documentation:
+
+ 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.