document preferred content for import/export

doc/bugs/export-tree_exports___34__small__34___files_even_if_they_don__39__t_match_the_wanted_expression/comment_4_aa029562ec76e83ecc5e6fc76355ad96._comment

@@ -0,0 +1,26 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 4"""
+ date="2020-08-10T19:18:13Z"
+ content="""
+Understandable mistake. If you might have more such files,
+you can `git config annex.dotfiles true`
+
+> Also, I was surprised to find that include= expressions were relative to
+> the part of the tree I was exporting and not the git-annex root ?
+
+Well, if you run `git annex export somesha --to remote`, all it knows is
+the tree for that sha, so it has to match relative to the top of that tree,
+and not whatever other tree it might be embedded in on master or wherever.
+
+When you run `git annex export master:subdir --to remote`, it has enough
+information that it could match relative to the top of master, but that
+would be inconsistent.
+
+And the same with a config setting annex-tracking-branch to master:subdir.
+
+Import does also do the same thing, it has to also for consistency of
+course.
+
+I have mentioned this in the docs now.
+"""]]

doc/git-annex-export.mdwn

@@ -23,9 +23,11 @@ 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
+When the remote has a preferred content expression set by
-through it, excluding annexed files it does not want from being exported
+[[git-annex-wanted]](1), the treeish is
-to it.
+filtered through it, excluding annexed files it does not want from
+being exported to it. (Note that things in the expression like
+"include=" match relative to the top of the treeish being exported.)
 
 Any files in the treeish that are stored on git will also be exported to
 the special remote.

doc/git-annex-import.mdwn

@@ -72,10 +72,10 @@ to tell it what branch to track. For example:
 	git config remote.myremote.annex-tracking-branch master
 	git annex sync --content
 
-If a preferred content expression is configured for the special remote,
+When the special remote has a preferred content expression set by
-it will be honored when importing from it. Files that are not preferred
+[[git-annex-wanted]](1), it will be honored when importing from it.
-content of the remote will not be imported from it, but will be left on the
+Files that are not preferred content of the remote will not be
-remote. 
+imported from it, but will be left on the remote.
 
 However, preferred content expressions that relate to the key
 can't be matched when importing, because the content of the file is not
@@ -84,6 +84,9 @@ set. This includes expressions containing "copies=", "metadata=", and other
 things that depend on the key. Preferred content expressions containing
 "include=", "exclude=" "smallerthan=", "largerthan=" will work.
 
+Things in the expression like "include=" match relative to the top of
+the tree of files on the remote, even when importing into a subdirectory.
+
 # OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE
 
 * `--content`, `--no-content`