Repository tuning parameters can now be passed when initializing a repository for the first time.

* init: Repository tuning parameters can now be passed when initializing a
  repository for the first time. For details, see
  http://git-annex.branchable.com/tuning/
* merge: Refuse to merge changes from a git-annex branch of a repo
  that has been tuned in incompatable ways.

3 files changed, 59 insertions, 0 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index c4586ba1d..06eb85e11 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -1839,6 +1839,12 @@ Here are all the supported configuration settings.
   Used by hook special remotes and external special remotes to record
   the type of the remote.
 
+* `annex.tune.objecthashdirectories`, `annex.tune.objecthashlower`, `annex.tune.branchhashdirectories`
+
+  These can be passed to `git annex init` to tune the repository.
+  They cannot be safely changed in a running repository.
+  For details, see <http://git-annex.branchable.com/tuning/>.
+
 # CONFIGURATION VIA .gitattributes
 
 The key-value backend used when adding a new file to the annex can be
diff --git a/doc/internals.mdwn b/doc/internals.mdwn
index b8cb559b6..4eb72ceac 100644
--- a/doc/internals.mdwn
+++ b/doc/internals.mdwn
@@ -257,3 +257,12 @@ Example:
 
 	ForgetGitHistory 1387325539.685136s
 	ForgetDeadRemotes 1387325539.685136s
+
+## `difference.log`
+
+Used when a repository has fundamental differences from other repositories,
+that should prevent merging.
+
+Example:
+
+	e605dca6-446a-11e0-8b2a-002170d25c55 [Version 5] timestamp=1422387398.30395s
diff --git a/doc/tuning.mdwn b/doc/tuning.mdwn
new file mode 100644
index 000000000..761071b6b
--- /dev/null
+++ b/doc/tuning.mdwn
@@ -0,0 +1,44 @@
+git-annex now has experimental support for tuning a repository for
+different work loads. 
+
+For example, a repository with a very large number of files in it may work
+better if git-annex uses some nonstandard hash format, for either the
+`.git/annex/objects/` directory, or for the log files in the git-annex
+branch.
+
+A repository can currently only be tuned when it is first created; this is
+done by passing `-c name=value` parameters to `git annex init`.
+
+For example, this will make git-annex use only 1 level for hash directories
+in `.git/annex/objects`:
+
+	git -c annex.tune.objecthashdirectories=1 annex init
+
+It's very important to keep in mind that this makes a nonstandard format
+git-annex repository. In general, this cannot safely be used with
+git-annex older than version 5.20150128. Older version of git-annex will
+not understand and will get confused and perhaps do bad things.
+
+Also, it's not safe to merge two separate git repositories that have been
+tuned differently (or one tuned and the other one not). git-annex will
+prevent merging their git-annex branches together, but it cannot prevent
+`git merge remote/master` merging two branches, and the result will be ugly
+at best (`git annex fix` can fix up the mess somewhat).
+
+Again, tuned repositories are an experimental feature; use with caution!
+
+The following tuning parameters are available:
+
+* `annex.tune.objecthashdirectories` (default: 2)  
+  Sets the number of hash directories to use in `.git/annex/objects/`
+
+* `annex.tune.objecthashlower` (default: false)
+  Set to true to make the hash directories in `.git/annex/objects/` use
+  all lower-case.
+
+* `annex.tune.branchhashdirectories` (default: 2)
+  Sets the number of hash directories to use in the git-annex branch.
+
+Note that git-annex will automatically propigate these setting to
+`.git/config` for tuned repsitories. You should never directly change
+these settings in `.git/config`