Merge commit 'b319ef7' into jc/maint-fix-test-perm

* commit 'b319ef7': (8132 commits)
  Add a small patch-mode testing library
  git-apply--interactive: Refactor patch mode code
  t8005: Nobody writes Russian in shift_jis
  Fix severe breakage in "git-apply --whitespace=fix"
  Update release notes for 1.6.4
  After renaming a section, print any trailing variable definitions
  Make section_name_match start on '[', and return the length on success
  send-email: detect cycles in alias expansion
  Show the presence of untracked files in the bash prompt.
  SunOS grep does not understand -C<n> nor -e
  Fix export_marks() error handling.
  git repack: keep commits hidden by a graft
  Add a test showing that 'git repack' throws away grafted-away parents
  git branch: clean up detached branch handling
  git branch: avoid unnecessary object lookups
  git branch: fix performance problem
  git svn: fix shallow clone when upstream revision is too new
  do_one_ref(): null_sha1 check is not about broken ref
  configure.ac: properly unset NEEDS_SSL_WITH_CRYPTO when sha1 func is missing
  janitor: useless checks before free
  ...

1 files changed, 34 insertions, 0 deletions

diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
new file mode 100644
index 0000000000..43dbe09f73
--- /dev/null
+++ b/Documentation/technical/api-allocation-growing.txt
@@ -0,0 +1,34 @@
+allocation growing API
+======================
+
+Dynamically growing an array using realloc() is error prone and boring.
+
+Define your array with:
+
+* a pointer (`ary`) that points at the array, initialized to `NULL`;
+
+* an integer variable (`alloc`) that keeps track of how big the current
+  allocation is, initialized to `0`;
+
+* another integer variable (`nr`) to keep track of how many elements the
+  array currently has, initialized to `0`.
+
+Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
+alloc)`.  This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+
+------------
+sometype *ary;
+size_t nr;
+size_t alloc
+
+for (i = 0; i < nr; i++)
+	if (we like ary[i] already)
+		return;
+
+/* we did not like any existing one, so add one */
+ALLOC_GROW(ary, nr + 1, alloc);
+ary[nr++] = value you like;
+------------
+
+You are responsible for updating the `nr` variable.