consistently use importKey when available

This avoids import with --no-content and with --content potentially
generating two different trees, leading to a merge conflict when run in
two different clones of a repo. And it's necessary groundwork to make
git-annex sync --no-content import from special remotes that support
importKey.

Only the directory special remote currently supports importKey, and it
generates the same key as git-annex usually does, so there is no
behavior change for it.

Future special remotes will need to take care when adding importKey,
if it generates different keys. Added some warnings about that to
comments.

This commit was sponsored by Noam Kremen on Patreon.

doc/design/external_special_remote_protocol/export_and_import_appendix.mdwn

@@ -186,7 +186,10 @@ support a request, it can reply with `UNSUPPORTED-REQUEST`.
   rather than `EXPECTED`.
 * `IMPORTKEY File`
   This only needs to be implemented if IMPORTKEYSUPPORTED indicates
-  it is supported.  
+  it is supported. And if a remote did not support it before, adding
+  it will make importing the same content as before generate a likely
+  different tree, which can lead to merge conflicts. So be careful
+  implementing this.  
   Generates a key by querying the remote for eg, a checksum.
   (See [[internals/key_format]] for details of how to format a key.)
   Any kind of key can be generated, depending on what the remote

doc/git-annex-import.mdwn

@@ -98,23 +98,7 @@ the tree of files on the remote, even when importing into a subdirectory.
   With --no-content, git-annex keys are generated from information
   provided by the special remote, without downloading it. Commands like
   `git-annex get` can later be used to download files, as desired.
-
-  The --no-content option is not supported by all special remotes,
-  and the kind of git-annex key that is generated is left up to
-  each special remote. So while the directory special remote hashes
-  the file and generates the same key it usually would, other
-  special remotes may use unusual keys like SHA1, or WORM, depending
-  on the limitations of the special remote. 
-
-  The annex.securehashesonly configuration, if set, will prevent
-  --no-content importing from a special remote that uses insecure keys.
-
-  Note that a different git tree may be generated when using
-  --no-content than would be generated when using --content, because
-  the options cause different kinds of keys to be used when importing
-  new/changed files. So mixing uses of --content and --no-content can
-  lead to merge conflicts in some situations. Some special remotes,
-  notably the directory special remote, avoid this problem.
+  The --no-content option is not supported by all special remotes.
 
 # IMPORTING FROM A DIRECTORY
 

doc/git-annex-sync.mdwn

@@ -108,12 +108,14 @@ received.
   This behavior can be overridden by configuring the preferred content
   of a repository. See [[git-annex-preferred-content]](1).
 
-  When `remote.<name>.annex-tracking-branch` is configured for a special remote
-  and that branch is checked out, syncing content will import changes from
-  the remote, merge them into the branch, and export any changes that have
-  been committed to the branch back to the remote. See 
-  See [[git-annex-import]](1) and [[git-annex-export]](1) for details about
-  how importing and exporting work.
+  When `remote.<name>.annex-tracking-branch` is configured for a special
+  remote and that branch is checked out, syncing with --content will
+  import changes from the remote, merge them into the branch, and export
+  any changes that have been committed to the branch back to the remote.
+  With --no-content, imports will only be made from special remotes that
+  support importing without transferting files, and no exports will be done.
+  See [[git-annex-import]](1) and [[git-annex-export]](1) for details
+  about how importing and exporting work.
 
 * `--content-of=path` `-C path`
 

doc/todo/sync_fast_import.mdwn

@@ -35,7 +35,18 @@ git-annex to use a different backend.
 > content, then the remote could say, don't use importKey by default.
 > (Or more likely, only the directory remote will be able to support
 > importKey by default..)
+> 
+> Problem: When annex.largefiles matches file content,
+> cannot use importKey. So then should sync --content not use importKey
+> then, risking generating a different tree? Or should it fail, even
+> though importing with content is possible?
+> 
+> > Well, different annex.largefiles settings in different clones 
+> > can already risk generating a different tree on import. So,
+> > the former option seems preferable.
 
 ---
 
 See also, [[todo/import_--no-content_largefiles_conflict]]
+
+> [[done]] --[[Joey]]