docs for export preferred content

This includes a note about how include= and exclude= match when exporting
a subtree. I don't know if the note is prominent enough, but the
behavior seems unsurprising enough.

CHANGELOG

@@ -5,6 +5,8 @@ git-annex (7.20190508) UNRELEASED; urgency=medium
   * Makefile: Added install-completions to install target.
   * Added the ability to run one job per CPU (core), by setting
     annex.jobs=cpus, or using option --jobs=cpus or -Jcpus.
+  * Honor preferred content of a special remote when exporting trees to it;
+    unwanted files are filtered out of the tree that is exported.
 
  -- Joey Hess <id@joeyh.name>  Mon, 06 May 2019 13:52:02 -0400
 

doc/git-annex-export.mdwn

@@ -23,6 +23,9 @@ The treeish to export can be the name of a git branch, or a tag, or any
 other treeish accepted by git, including eg master:subdir to only export a
 subdirectory from a branch.
 
+When the remote has a preferred content setting, the treeish is filtered
+through it, excluding files it does not want from being exported to it.
+
 Repeated exports are done efficiently, by diffing the old and new tree,
 and transferring only the changed files, and renaming files as necessary.
 
@@ -65,6 +68,8 @@ let an export overwrite the modified file; then `git annex import`
 will create a sequence of commits that includes the modified file,
 so the overwritten modification is not lost.)
 
+# PREFERRED 
+
 # OPTIONS
 
 * `--to=remote`
@@ -132,6 +137,8 @@ export`, it will detect the export conflict, and resolve it.
 
 [[git-annex-sync]](1)
 
+[[git-annex-preferred-content]](1)
+
 # HISTORY
 
 The `export` command was introduced in git-annex version 6.20170925.

doc/git-annex-preferred-content.mdwn

@@ -37,13 +37,17 @@ elsewhere to allow removing it).
   Match files to include, or exclude.
 
   While --include=glob and --exclude=glob match files relative to the current
-  directory, preferred content expressions always match files relative to the
-  top of the git repository. 
+  directory, preferred content expressions match files relative to the
+  top of the git repository.
 
   For example, suppose you put files into `archive` directories
   when you're done with them. Then you could configure your laptop to prefer
   to not retain those files, like this: `exclude=*/archive/*`
 
+  When a subdirectory is being exported to a special remote (see
+  [[git-annex-export]](1)), these match relative to the top of the
+  subdirectory.
+
 * `copies=number`
 
   Matches only files that git-annex believes to have the specified number

doc/todo/export_preferred_content.mdwn

@@ -11,7 +11,9 @@ been listened to.
 
 It seems doable to make `git annex export` honor whatever
 preferred content settings have been configured for the remote.
-(And `git annex sync --content` too.)
+(And `git annex sync --content` too.)  
+
+> done
 
 Problem: A preferred content expression include=subdir/foo or
 exclude=subdir/bar matches relative to the top of the repository.
@@ -24,6 +26,8 @@ It may be better to add a note that preferred content expressions include=
 exclude= etc match relative to the top of the exported tree when exporting
 a subtree.
 
+> done
+
 ----
 
 > `git annex import` of a tree from a special remote would also be
@@ -60,10 +64,23 @@ a subtree.
 > version of the branch for preferred content and location tracking.
 > (And use of `git-annex forget` could break it.)
 > 
-> It seems easier to instead record the tree of excluded files somewhere,
-> Logs.Export already records the whole exported tree in the git-annex
-> branch, so extend it to also record the tree of excluded files.
-> Complication: Export conflicts.
+> Logs.Export already records the tree that the user chose to export
+> into the git-annex branch. Should excluded files be present in that
+> tree or not? If not, the diff from that tree to the remote tracking
+> branch will be the excluded files. Another good reason to do that
+> is that if the preferred content settings change, the next export
+> will pick up on the change, since the exported tree differs from the tree
+> to be exported.
+> 
+> So, plan: Make export of a tree filter that tree through the preferred
+> content of the remote, and use the new tree as the tree that really
+> gets exported, recording it in the git-annex branch. But the remote
+> tracking branch will point to the commit that the user chose to export.
+> > (done)
+> 
+> The import then just needs to diff between the last exported tree and
+> and the remote tracking branch to get the files that were excluded,
+> and add them back into the imported tree.
 
 ---