improve documentation

doc/bugs/Deleted_files_not_considered_with_wanted__61____34__anything__34__.mdwn

@@ -76,3 +76,5 @@ Yes.  Thank you!  :>
 
 [[!meta author=kyle]]
 [[!tag projects/datalad]]
+
+> [[done]] --[[Joey]]

doc/bugs/Deleted_files_not_considered_with_wanted__61____34__anything__34__/comment_1_03eebb6527c364552b8f81c12616e926._comment

@@ -0,0 +1,21 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2020-04-13T16:03:16Z"
+ content="""
+All of the commands you ran looked only at files in the current tree,
+so of course did not operate on deleted files. Eg, "git annex get" and "git
+annex get ." are identical, and obviously the current directory does not
+contain any deleted files.
+
+But there are commands that do operate on deleted files, including eg `git
+annex sync --content --all` and `git annex get --all`. Those commands will
+honor preferred content settings including "anything" when operating on
+deleted files. (The assistant also periodically does.)
+
+I've added a note to that effect to the preferred content
+documentation. Also several command's man pages didn't make entirely
+explicit that they operated on files in the current tree
+(although the main git-annex man page does document that),
+so improved that documentation too.
+"""]]

doc/git-annex-copy.mdwn

@@ -10,6 +10,9 @@ git annex copy `[path ...] [--from=remote|--to=remote]`
 
 Copies the content of files from or to another remote.
 
+With no parameters, operates on all annexed files in the current directory.
+Paths of files or directories to operate on can be specified.
+
 # OPTIONS
 
 * `--from=remote`
@@ -38,7 +41,7 @@ Copies the content of files from or to another remote.
 
 * `--auto`
 
-  Rather than copying all files, only copy files that don't yet have
+  Rather than copying all specified files, only copy files that don't yet have
   the desired number of copies, or that are preferred content of the
   destination repository. See [[git-annex-preferred-content]](1)
 

doc/git-annex-drop.mdwn

@@ -18,6 +18,9 @@ in some other repository.
 Content that is required to be stored in the repository will not be dropped
 even if enough copies exist elsewhere. See [[git-annex-required]](1).
 
+With no parameters, tries to drop all annexed files in the current directory.
+Paths of files or directories to drop can be specified.
+
 # OPTIONS
 
 * `--from=remote`
@@ -44,7 +47,8 @@ even if enough copies exist elsewhere. See [[git-annex-required]](1).
   Rather than specifying a filename or path to drop, this option can be
   used to drop all available versions of all files.
 
-  This is the default behavior when running git-annex drop in a bare repository.
+  This is the default behavior when running git-annex drop in a bare
+  repository.
 
   Note that this bypasses checking the .gitattributes annex.numcopies
   setting and required content settings.

doc/git-annex-get.mdwn

@@ -12,12 +12,16 @@ Makes the content of annexed files available in this repository. This
 will involve copying them from a remote repository, or downloading them,
 or transferring them from some kind of key-value store.
 
+With no parameters, gets all annexed files in the current directory whose
+content was not already present. Paths of files or directories to get can
+be specified.
+
 # OPTIONS
 
 * `--auto`
 
-  Rather than getting all files, get only files that don't yet have
+  Rather than getting all specified files, get only files that don't yet
-  the desired number of copies, or that are preferred content of the
+  have the desired number of copies, or that are preferred content of the
   repository. See [[git-annex-preferred-content]](1)
 
 * `--from=remote`

doc/git-annex-move.mdwn

@@ -10,6 +10,9 @@ git annex move `[path ...] [--from=remote|--to=remote|--to=here]`
 
 Moves the content of files from or to another remote.
 
+With no parameters, operates on all annexed files in the current directory.
+Paths of files or directories to operate on can be specified.
+
 # OPTIONS
 
 * `--from=remote`

doc/git-annex-preferred-content.mdwn

@@ -48,6 +48,10 @@ elsewhere to allow removing it).
   [[git-annex-export]](1)) and [[git-annex-import]](1), these match relative
   to the top of the subdirectory.
 
+  Note that, when a command is run with the `--all` option, or in a bare
+  repository, there is no filename associated with an annexed object,
+  and so "include=" and "exclude=" will not match.
+
 * `copies=number`
 
   Matches only files that git-annex believes to have the specified number
@@ -160,6 +164,10 @@ elsewhere to allow removing it).
 
   (If no directory name is configured, it uses "public" by default.)
 
+  Note that, when a command is run with the `--all` option, or in a bare
+  repository, there is no filename associated with an annexed object,
+  and so "inpreferreddir" will not match.
+
 * `standard`
 
   git-annex comes with some built-in preferred content expressions, that

doc/git-annex-sync.mdwn

@@ -99,9 +99,9 @@ received.
   The `annex.synccontent` configuration can be set to true to make content
   be synced by default.
 
-  Normally this tries to get each annexed file that the local repository
+  Normally this tries to get each annexed file that is in the working tree
-  does not yet have, and then copies each file to every remote that it
+  and whose content the local repository does not yet have, and then copies
-  is syncing with.
+  each file to every remote that it is syncing with.
   This behavior can be overridden by configuring the preferred content
   of a repository. See [[git-annex-preferred-content]](1).
 

doc/preferred_content/standard_groups.mdwn

@@ -51,6 +51,11 @@ All content is wanted. Even content of old/deleted files.
 
 `anything`
 
+(Note that most git-annex commands operate on files present in the
+working tree by default, and using this does not change that. The assistant
+does operate on deleted files, and other commands can be made to do so with
+the --all option.)
+
 ### incrementalbackup
 
 Only wants content that's not already backed up to another backup