added git-annex satisfy

This ended up having an interface like sync, rather than like get/copy/drop.
That let it be implemented in terms of sync, which took a lot less code.
Also, it lets it handle many of the edge cases that sync does, such as
getting files that are not visible in a --hide-missing branch, and sending
files to exporttree remotes.

As well as being easier to implement, `git-annex satisfy myremote` makes
sense as it satisfies the preferred content settings of the remote.
`git-annex satisfy somefile` does not form a sentence that makes sense. So
while -C can be a little bit annoying, it still makes sense to have this
syntax.

Note that, while I initially thought this would also satisfy numcopies, it
does not. Arguably it ought to. But, sync does not send files in order to
satisfy numcopies, it only sends files to satisfy preferred content. And
it's important that this transfer the same files as sync does, because
it will probably be used in a workflow where the user sometimes syncs and
sometimes satisfies, and does not expect satisfy to do things that sync
would not do.

(Also opened a new bug that also affects sync et all, not only this command.)

Sponsored-by: Nicholas Golder-Manning on Patreon

doc/bugs/sync_-C_can_export_other_files.mdwn

@@ -0,0 +1,14 @@
+When an exporttree=yes remote has had a tree exported to it, but eg with
+`git-annex export master --to foo --fast`, so not all the files have been
+sent to it yet, `git-annex sync -Cfoo` will also export files in other
+directories to it.
+
+This seems like a bug, it ought to only export any files in the specified
+directory.
+
+Another way this can happen is `git-annex sync -Cfoo`, when file bar
+has changed. Currently this exports bar to the export remote, but does
+not send it to any other remotes, since it's not in directory foo.
+
+Also this affects `git-annex satisfy`, and other related commands too.
+--[[Joey]]

doc/git-annex-pull.mdwn

@@ -33,7 +33,7 @@ to the parent branch or metadata.
 Normally this tries to download the content of each annexed file,
 from any remote that it's pulling from that has a copy. 
 To control which files it downloads, configure the preferred
-content of the local repository.It will also drop files from a
+content of the local repository. It will also drop files from a
 remote that are not preferred content of the remote.
 See [[git-annex-preferred-content]](1).
 

doc/git-annex-satisfy.mdwn

@@ -4,21 +4,34 @@ git-annex satisfy - transfer and drop content as configured
 
 # SYNOPSIS
 
-git annex satisffy `[path ...]`
+git annex satisfy `[remote ...]`
 
 # DESCRIPTION
 
-This transfers and drops content to satisfy the numcopies and preferred
-content settings of the local repository and remotes.
+This transfers and drops content of annexed files to work toward satisfying
+the preferred content settings of the local repository and remotes.
 
 It does the same thing as `git-annex sync --content` without the pulling
-and pushing of git repositories.
-
-By default it operates on all annexed files in the current directory and
-its subdirectories. Paths of files or directories can also be specified.
+and pushing of git repositories, and without changing the trees that are
+imported to or exported from special remotes.
 
 # OPTIONS
 
+* `[remote]`
+
+  By default this command operates on all remotes, except for remotes
+  that have `remote.<name>.annex-sync` set to false.
+
+  By specifying the names of remotes (or remote groups), you can control
+  which ones to operate on.
+
+* `--content-of=path` `-C path`
+
+  Operate on only files in the specified path. The default is to operate on
+  all files in the working tree.
+
+  This option can be repeated multiple times with different paths.
+
 * `--jobs=N` `-JN`
 
   Enables parallel processing with up to the specified number of jobs
@@ -28,47 +41,13 @@ its subdirectories. Paths of files or directories can also be specified.
 
 * `--all` `-A`
 
-  Operate on all objects stored in the git annex, not only objects used by
-  currently existing files. 
-  
-  However, this bypasses checking the .gitattributes annex.numcopies
-  setting when dropping files.
+  Usually this command operates on annexed files in the current branch.
+  This option makes it operate on all available versions of all annexed files
+  (when preferred content settings allow).
 
-  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.
-
-* `--unused`
-
-  Operate on files found by last run of git-annex unused.
-
-* `--failed`
-
-  Operate on files that have recently failed to be transferred.
-
-* matching options
-
-  The [[git-annex-matching-options]](1)
-  can be used to control what files to operate on.
-
-* `--json`
-
-  Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
-
-* `--json-progress`
-
-  Include progress objects in JSON output.
-
-* `--json-error-messages`
-
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Note that preferred content settings that use `include=` or `exclude=`
+  will only match the version of files currently in the work tree, but not
+  past versions of files.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
@@ -78,8 +57,6 @@ its subdirectories. Paths of files or directories can also be specified.
 
 [[git-annex-sync]](1)
 
-[[git-annex-preferred-numcopies]](1)
-
 [[git-annex-preferred-content]](1)
 
 # AUTHOR

doc/git-annex.mdwn

@@ -138,10 +138,9 @@ content from the key-value store.
   
   See [[git-annex-assist]](1) for details.
 
-* `satisfy [path ...]`
+* `satisfy [remote ...]`
 
-  Satisfy numcopies and preferred content settings by transferring
-  and dropping content.
+  Satisfy preferred content settings by transferring and dropping content.
   
   See [[git-annex-satisfy]](1) for details.
 

doc/todo/new_command_for_syncing_content_only.mdwn

@@ -19,3 +19,5 @@ What would be a good name for such a command?  --[[Joey]]
 > How about `git-annex port` as it carries content over like a luggage carrier aka. porter?
 > Another one that comes to mind is `git-annex shuttle` but that could be semantically too
 > similar to `git-annex assist`, perhaps. --[[jkniiv]]
+
+>> `git-annex satisfy` [[done]] --[[Joey]]