Added --expected-present file matching option

5 files changed, 44 insertions, 3 deletions

diff --git a/CHANGELOG b/CHANGELOG
index e01b60df1b..c832cc3236 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -21,6 +21,7 @@ git-annex (10.20231228) UNRELEASED; urgency=medium
   * Added configs annex.stalldetection-download, annex.stalldetection-upload,
     annex.bwlimit-download, annex.bwlimit-upload,
     and similar per-remote configs.
+  * Added --expected-present file matching option.
 
  -- Joey Hess <id@joeyh.name>  Fri, 29 Dec 2023 11:52:06 -0400
 
diff --git a/CmdLine/GitAnnex/Options.hs b/CmdLine/GitAnnex/Options.hs
index b3c21aeece..694b60d240 100644
--- a/CmdLine/GitAnnex/Options.hs
+++ b/CmdLine/GitAnnex/Options.hs
@@ -293,7 +293,7 @@ keyMatchingOptions' :: [AnnexOption]
 keyMatchingOptions' = 
 	[ annexOption (setAnnexState . Limit.addIn) $ strOption
 		( long "in" <> short 'i' <> metavar paramRemote
-		<> help "match files present in a remote"
+		<> help "match files present in a repository"
 		<> hidden
 		<> completeRemotes
 		)
@@ -386,6 +386,11 @@ keyMatchingOptions' =
 		<> help "match files that are locked"
 		<> hidden
 		)
+	, annexFlag (setAnnexState Limit.addExpectedPresent)
+		( long "expected-present"
+		<> help "match files expected to be present"
+		<> hidden
+		)
 	]
 
 -- Options to match files which may not yet be annexed.
diff --git a/Limit.hs b/Limit.hs
index 26448594b9..ad17520df8 100644
--- a/Limit.hs
+++ b/Limit.hs
@@ -330,6 +330,22 @@ addIn s = do
 				then return False
 				else inAnnex key
 
+{- Limit to content that location tracking expects to be present
+ - in the current repository. Does not verify inAnnex. -}
+addExpectedPresent :: Annex ()
+addExpectedPresent = do
+	hereu <- getUUID
+	addLimit $ Right $ MatchFiles
+		{ matchAction = const $ checkKey $ \key -> do
+			us <- Remote.keyLocations key
+			return $ hereu `elem` us
+		, matchNeedsFileName = False
+		, matchNeedsFileContent = False
+		, matchNeedsKey = True
+		, matchNeedsLocationLog = True
+		, matchDesc = matchDescSimple "expected-present"
+		}
+
 {- Limit to content that is currently present on a uuid. -}
 limitPresent :: Maybe UUID -> MatchFiles Annex
 limitPresent u = MatchFiles
diff --git a/doc/git-annex-matching-options.mdwn b/doc/git-annex-matching-options.mdwn
index 6a0d8a0119..ea29f98848 100644
--- a/doc/git-annex-matching-options.mdwn
+++ b/doc/git-annex-matching-options.mdwn
@@ -60,12 +60,15 @@ in either of two repositories.
 * `--in=repository`
 
   Matches only when git-annex believes that the content is present in a
-  repository. Note that it does not check the repository to verify
-  that it still has the content.
+  repository.
 
   The repository should be specified using the name of a configured remote,
   or the UUID or description of a repository. For the current repository,
   use `--in=here`
+  
+  Note that this does not check remote repositories to verify that content
+  is still present on them. However, when checking the current repository,
+  it does verify that content is present in it.
 
 * `--in=repository@{date}`
 
@@ -80,6 +83,20 @@ in either of two repositories.
   free up disk space. The next day, you can get back the files you dropped
   using `git annex get . --in=here@{yesterday}`
 
+* `--expected-present`
+
+  Matches only when git-annex believes that the content is present 
+  in the local repository.
+
+  This is like `--in=here`, except it does not verify that the content
+  is actually present. So it can be used in situations where the location
+  tracking information is known to be out of date.
+
+  For example, if a repository is being restored from a backup
+  that did not include the git-annex objects, this could be used to get
+  back all files that were expected to be in it: 
+  `git-annex get --expected-present`
+
 * `--copies=number`
 
   Matches only when git-annex believes there are the specified number
diff --git a/doc/todo/option_to_limit_to_files_that_are_expected_to_be_present.mdwn b/doc/todo/option_to_limit_to_files_that_are_expected_to_be_present.mdwn
index 53917edd78..2ed8715fc5 100644
--- a/doc/todo/option_to_limit_to_files_that_are_expected_to_be_present.mdwn
+++ b/doc/todo/option_to_limit_to_files_that_are_expected_to_be_present.mdwn
@@ -3,3 +3,5 @@ situation where my repo was copied from elsewhere but missing the object
 files, and I wanted to get back the same objects. So I had to disable that
 check. So an option that checks for files expected to be here would be
 useful. --[[Joey]]
+
+> [[done]] as --expected-present --[[Joey]]