From 6f35b576d78fcde4c572ad8f8165dd063fdd7aef Mon Sep 17 00:00:00 2001
From: Joey Hess <joeyh@joeyh.name>
Date: Tue, 19 Nov 2019 13:26:27 -0400
Subject: [PATCH] encourage use of import from directory special remote rather
 than legacy interface

---
 Command/Import.hs         |  2 +-
 doc/git-annex-import.mdwn | 17 +++++++++++------
 doc/git-annex.mdwn        |  5 ++---
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/Command/Import.hs b/Command/Import.hs
index ca4448808a..0488ef4cb7 100644
--- a/Command/Import.hs
+++ b/Command/Import.hs
@@ -39,7 +39,7 @@ cmd :: Command
 cmd = notBareRepo $
 	withGlobalOptions [jobsOption, jsonOptions, fileMatchingOptions] $
 		command "import" SectionCommon 
-			"import files from elsewhere into the repository"
+			"add a tree of files to the repository"
 			(paramPaths ++ "|BRANCH[:SUBDIR]")
 			(seek <$$> optParser)
 
diff --git a/doc/git-annex-import.mdwn b/doc/git-annex-import.mdwn
index 89a30e82c5..1b7239f09b 100644
--- a/doc/git-annex-import.mdwn
+++ b/doc/git-annex-import.mdwn
@@ -1,16 +1,16 @@
 # NAME
 
-git-annex import - add files from a non-versioned directory or a special remote
+git-annex import - add a tree of files to the repository
 
 # SYNOPSIS
 
-git annex import `[path ...]` | git annex import --from remote branch[:subdir]
+git annex import --from remote branch[:subdir] | `[path ...]`
 
 # DESCRIPTION
 
-This command is a way to import files from elsewhere into your git-annex
-repository. It can import files from a directory into your repository, 
-or it can import files from a git-annex special remote.
+This command is a way to import a tree of files from elsewhere into your
+git-annex repository. It can import files from a git-annex special remote,
+or from a directory.
 
 # IMPORTING FROM A SPECIAL REMOTE
 
@@ -30,7 +30,8 @@ remote.
 
 You can only import from special remotes that were configured with
 `importtree=yes` when set up with [[git-annex-initremote]](1). Only some
-kinds of special remotes will let you configure them this way.
+kinds of special remotes will let you configure them this way. A perhaps
+non-exhastive list is the directory, s3, and adb special remotes.
 
 To import from a special remote, you must specify the name of a branch.
 A corresponding remote tracking branch will be updated by `git annex
@@ -88,6 +89,10 @@ things that depend on the key. Preferred content expressions containing
 When run with a path, `git annex import` moves files from somewhere outside
 the git working copy, and adds them to the annex.
 
+This is a legacy interface. It is still supported, but please consider
+switching to importing from a directory special remote instead, using the
+interface documented above.
+
 Individual files to import can be specified. If a directory is specified,
 the entire directory is imported.
   
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 43f6560484..b191e3a5b0 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -146,10 +146,9 @@ subdirectories).
   
   See [[git-annex-rmurl]](1) for details.
 
-* `import [path ...]`
+* `import --from remote branch[:subdir] | [path ...]`
 
-  Add files from a non-version-controlled directory or a 
-  special remote into the annex.
+  Add a tree of files to the repository.
   
   See [[git-annex-import]](1) for details.