document git-annex satisfy

CHANGELOG

@@ -1,5 +1,9 @@
 git-annex (10.20230627) UNRELEASED; urgency=medium
 
+  * satify: New command that gets/sends/drops content to satisfy
+    numcopies and preferred content settings. This is similar to
+    the --content part of git-annex sync, but with an interface
+    more like get/move/drop.
   * reinject: Added --guesskeys option.
   * diffdriver: Added --text option for easy diffing of the contents of
     annexed text files.

doc/git-annex-pull.mdwn

@@ -136,6 +136,8 @@ See [[git-annex-preferred-content]](1).
 
 [[git-annex-preferred-content]](1)
 
+[[git-annex-satisfy]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/git-annex-push.mdwn

@@ -134,6 +134,8 @@ See [[git-annex-preferred-content]](1).
 
 [[git-annex-preferred-content]](1)
 
+[[git-annex-satisfy]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/git-annex-satisfy.mdwn

@@ -0,0 +1,89 @@
+# NAME
+
+git-annex satisfy - transfer and drop content as configured
+
+# SYNOPSIS
+
+git annex satisffy `[path ...]`
+
+# DESCRIPTION
+
+This transfers and drops content to satisfy the numcopies and preferred
+content settings of the local repository and remotes.
+
+It does the same thing as `git-annex sync --content` without the pulling
+and pushing of git repositories.
+
+By default it operates on all annexed files in the current directory and
+its subdirectories. Paths of files or directories can also be specified.
+
+# OPTIONS
+
+* `--jobs=N` `-JN`
+
+  Enables parallel processing with up to the specified number of jobs
+  running at once. For example: `-J10`
+
+  Setting this to "cpus" will run one job per CPU core.
+
+* `--all` `-A`
+
+  Operate on all objects stored in the git annex, not only objects used by
+  currently existing files. 
+  
+  However, this bypasses checking the .gitattributes annex.numcopies
+  setting when dropping files.
+
+  This is the default behavior when running git-annex in a bare repository.
+
+* `--branch=ref`
+
+  Operate on files in the specified branch or treeish.
+
+  Like --all, this bypasses checking the .gitattributes annex.numcopies
+  setting when dropping files.
+
+* `--unused`
+
+  Operate on files found by last run of git-annex unused.
+
+* `--failed`
+
+  Operate on files that have recently failed to be transferred.
+
+* matching options
+
+  The [[git-annex-matching-options]](1)
+  can be used to control what files to operate on.
+
+* `--json`
+
+  Enable JSON output. This is intended to be parsed by programs that use
+  git-annex. Each line of output is a JSON object.
+
+* `--json-progress`
+
+  Include progress objects in JSON output.
+
+* `--json-error-messages`
+
+  Messages that would normally be output to standard error are included in
+  the JSON instead.
+
+* Also the [[git-annex-common-options]](1) can be used.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-sync]](1)
+
+[[git-annex-preferred-numcopies]](1)
+
+[[git-annex-preferred-content]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.

doc/git-annex-sync.mdwn

@@ -76,6 +76,8 @@ content by default. That will change in a future version of git-annex,
 
 [[git-annex-assist]](1)
 
+[[git-annex-satisfy]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/git-annex.mdwn

@@ -138,6 +138,13 @@ content from the key-value store.
   
   See [[git-annex-assist]](1) for details.
 
+* `satisfy [path ...]`
+
+  Satisfy numcopies and preferred content settings by transferring
+  and dropping content.
+  
+  See [[git-annex-satisfy]](1) for details.
+
 * `mirror [path ...] [--to=remote|--from=remote]`
 
   Mirror content of files to/from another repository.

git-annex.cabal

@@ -118,6 +118,7 @@ Extra-Source-Files:
   doc/git-annex-restage.mdwn
   doc/git-annex-resolvemerge.mdwn
   doc/git-annex-rmurl.mdwn
+  doc/git-annex-satisfy.mdwn
   doc/git-annex-schedule.mdwn
   doc/git-annex-semitrust.mdwn
   doc/git-annex-setkey.mdwn