--branch, stage 1

Added --branch option to copy, drop, fsck, get, metadata, mirror, move, and
whereis commands. This option makes git-annex operate on files that are
included in a specified branch (or other treeish).

The names of the files from the branch that are being operated on are not
displayed yet; only the keys. Displaying the filenames will need changes
to every affected command.

Also, note that --branch can be specified repeatedly. This is not really
documented, but seemed worth supporting, especially since we may later want
the ability to operate on all branches matching a refspec. However, when
operating on two branches that contain the same key, that key will be
operated on twice.

9 files changed, 52 insertions, 0 deletions

diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn
index 5361e970c..185333446 100644
--- a/doc/git-annex-copy.mdwn
+++ b/doc/git-annex-copy.mdwn
@@ -51,6 +51,10 @@ Copies the content of files from or to another remote.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn
index 0bbbd78df..7b052bee0 100644
--- a/doc/git-annex-drop.mdwn
+++ b/doc/git-annex-drop.mdwn
@@ -42,14 +42,30 @@ safe to do so.
 
   This is the default behavior when running git-annex drop in a bare repository.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
+* `--branch=ref`
+
+  Drop files in the specified branch or treeish.
+
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * `--unused`
 
   Drop files found by last run of git-annex unused.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * `--key=keyname`
 
   Use this option to drop a specified key.
 
+  Note that this bypasses checking the .gitattributes annex.numcopies
+  setting.
+
 * file matching options
 
   The [[git-annex-matching-options]](1)
diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn
index 4b3b51040..2500ba977 100644
--- a/doc/git-annex-fsck.mdwn
+++ b/doc/git-annex-fsck.mdwn
@@ -72,6 +72,10 @@ With parameters, only the specified files are checked.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn
index 7faa5fd57..34b698084 100644
--- a/doc/git-annex-get.mdwn
+++ b/doc/git-annex-get.mdwn
@@ -57,6 +57,10 @@ or transferring them from some kind of key-value store.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index 448784b50..fe344ff5e 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -75,6 +75,11 @@ When run without any -s or -t parameters, displays the current metadata.
 
   Specify instead of a file to get/set metadata on all known keys.
 
+* `--branch=ref`
+
+  Specify instead of a file to get/set metadata on all files in the
+  specified branch or treeish.
+
 * `--unused`
 
   Specify instead of a file to get/set metadata on
diff --git a/doc/git-annex-mirror.mdwn b/doc/git-annex-mirror.mdwn
index 9c07d2b4c..9cc503f26 100644
--- a/doc/git-annex-mirror.mdwn
+++ b/doc/git-annex-mirror.mdwn
@@ -46,6 +46,13 @@ contents. Use [[git-annex-sync]](1) for that.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
+  Like --all, this bypasses checking the .gitattributes annex.numcopies
+  setting when dropping files.
+
 * file matching options
 
   The [[git-annex-matching-options]](1)
diff --git a/doc/git-annex-move.mdwn b/doc/git-annex-move.mdwn
index 85af4aa19..2d1b2a896 100644
--- a/doc/git-annex-move.mdwn
+++ b/doc/git-annex-move.mdwn
@@ -34,6 +34,10 @@ Moves the content of files from or to another remote.
 
   This is the default behavior when running git-annex in a bare repository.
 
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
 * `--unused`
 
   Operate on files found by last run of git-annex unused.
diff --git a/doc/git-annex-whereis.mdwn b/doc/git-annex-whereis.mdwn
index 4611468ba..b95033cbd 100644
--- a/doc/git-annex-whereis.mdwn
+++ b/doc/git-annex-whereis.mdwn
@@ -35,6 +35,10 @@ For example:
 
   Show whereis information for all known keys.
 
+* `--branch=ref`
+
+  Show whereis information for files in the specified branch or treeish.
+
 * `--unused`
 
   Show whereis information for files found by last run of git-annex unused.
diff --git a/doc/todo/operate_on_branch_contents.mdwn b/doc/todo/operate_on_branch_contents.mdwn
index f3ad9426f..eb2f00912 100644
--- a/doc/todo/operate_on_branch_contents.mdwn
+++ b/doc/todo/operate_on_branch_contents.mdwn
@@ -22,3 +22,7 @@ or `refs/tags/*` can be operated on. --[[Joey]]
 > work tree file, but something to display while operating on an item.
 > 
 > Not a hard change to make, but an extensive one. --[[Joey]]
+
+>> I've implemented the first part of this, so --branch works
+>> but the name of the key is shown, rather than the file from the branch.
+>> --[[Joey]]