document preferred content for import/export

diff --git a/doc/bugs/export-tree_exports___34__small__34___files_even_if_they_don__39__t_match_the_wanted_expression/comment_4_aa029562ec76e83ecc5e6fc76355ad96._comment b/doc/bugs/export-tree_exports___34__small__34___files_even_if_they_don__39__t_match_the_wanted_expression/comment_4_aa029562ec76e83ecc5e6fc76355ad96._comment
new file mode 100644 (file)
index 0000000..e964b73
--- /dev/null
+++ b/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.
+"""]]

diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn
index 39e697b7369dca3b528e1d556feacfc4f93e63cc..2c42a8f376721894b71b23f398e2ec271d82bc66 100644 (file)
--- a/doc/git-annex-export.mdwn
+++ b/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
-through it, excluding annexed files it does not want from being exported
-to it.
+When the remote has a preferred content expression set by
+[[git-annex-wanted]](1), the treeish is
+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.

diff --git a/doc/git-annex-import.mdwn b/doc/git-annex-import.mdwn
index 7566bb5df65f71231bf543bafb48f22480beb358..7501b30f8cea858390bc4e651f26c5d1e2324336 100644 (file)
--- a/doc/git-annex-import.mdwn
+++ b/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,
-it will be honored when importing from it. Files that are not preferred
-content of the remote will not be imported from it, but will be left on the
-remote. 
+When the special remote has a preferred content expression set by
+[[git-annex-wanted]](1), it will be honored when importing from it.
+Files that are not preferred content of the remote will not be
+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`