From a354263a197a7094eec73a0dd60c31eccdf43977 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 10 Aug 2020 15:35:26 -0400 Subject: [PATCH] document preferred content for import/export --- ..._aa029562ec76e83ecc5e6fc76355ad96._comment | 26 +++++++++++++++++++ doc/git-annex-export.mdwn | 8 +++--- doc/git-annex-import.mdwn | 11 +++++--- 3 files changed, 38 insertions(+), 7 deletions(-) create mode 100644 doc/bugs/export-tree_exports___34__small__34___files_even_if_they_don__39__t_match_the_wanted_expression/comment_4_aa029562ec76e83ecc5e6fc76355ad96._comment 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 index 0000000000..e964b73b4f --- /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 39e697b736..2c42a8f376 100644 --- 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 7566bb5df6..7501b30f8c 100644 --- 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`