Merge branch 'dropproof'

doc/bugs/concurrent_drop--from_presence_checking_failures.mdwn

@@ -2,6 +2,8 @@ Concurrent dropping of a file has problems when drop --from is
 used. (Also when the assistant or sync --content decided to drop from a
 remote.)
 
+> Now [[fixed|done]] --[[Joey]]
+
 [[!toc]]
 
 # refresher
@@ -73,6 +75,8 @@ as part of its check of numcopies, and keep it locked
 while it's asking B to drop it. Then when B tells A to drop it,
 it'll be locked and that'll fail (and vice-versa).
 
+> Done, and verified the fix works in this situation.
+
 # the bug part 2
 
 <pre>
@@ -116,6 +120,8 @@ Note that this is analgous to the fix above; in both cases
 the change is from checking if content is in a location, to locking it in
 that location while performing a drop from another location.
 
+> Done, and verified the fix works in this situation.
+
 # the bug part 3 (where it gets really nasty)
 
 <pre>
@@ -198,6 +204,9 @@ never entirely lost.
 Dipping below desired numcopies in an unusual race condition, and then
 doing extra work later to recover may be good enough.
 
+> Implemented, and I've now verified this solves the case above.
+> Indeed, neither drop succeeds, because no copy can be locked.
+
 ### to drop from local repo
 
 When dropping an object from the local repo, lock it for drop,
@@ -339,3 +348,22 @@ A drops                    B keeps                    C keeps
 It can race other ways, but they all work out the same way essentially,
 due to the locking.
 </pre>
+
+# the bug, with moves
+
+`git annex move --from remote` is the same as a copy followed by drop --from,
+so the same bug can occur then.
+
+But, the implementation differs from Command.Drop, so will also
+need some changes.
+
+Command.Move.toPerform already locks local content for removal before
+removing it, of course. So, that will interoperate fine with
+concurrent drops/moves. Seems fine as-is.
+
+Command.Move.fromPerform simply needs to lock the local content
+in place before dropping it from the remote. This satisfies the need
+for 1 locked copy when dropping from a remote, and so is sufficent to
+fix the bug.
+
+> done

doc/git-annex-shell.mdwn

@@ -43,6 +43,17 @@ first "/~/" or "/~user/" is expanded to the specified home directory.
   Exits 100 if it's unable to tell (perhaps the key is in the process of
   being removed from the annex).
 
+* lockcontent directory key
+
+  This locks a key's content in place in the annex, preventing it from
+  being dropped.
+
+  Once the content is successfully locked, outputs "OK". Then the content
+  remains locked until a newline is received from the caller or the
+  connection is broken.
+
+  Exits nonzero if the content is not present, or could not be locked.
+
 * dropkey directory [key ...]
 
   This drops the annexed data for the specified keys.