a325524454
Added a --json-exceptions option, which makes some exceptions be output in json. The distinction is that --json-error-messages is for messages relating to a particular ActionItem, while --json-exceptions is for messages that are not, eg ones for a file that does not exist. It's unfortunate that we need two switches with such a fine distinction between them, but I'm worried about maintaining backwards compatability in the json output, to avoid breaking anything that parses it, and this was the way to make sure I didn't. toplevelWarning is generally used for the latter kind of message. And the other calls to toplevelWarning could be converted to showException. The only possible gotcha is that if toplevelWarning is ever called after starting acting on a file, it will add to the --json-error-messages of the json displayed for that file and converting to showException would be a behavior change. That seems unlikely, but I didn't convery everything to avoid needing to satisfy myself it was not a concern. Sponsored-by: Dartmouth College's Datalad project
158 lines
4.2 KiB
Markdown
158 lines
4.2 KiB
Markdown
# NAME
|
|
|
|
git-annex drop - remove content of files from repository
|
|
|
|
# SYNOPSIS
|
|
|
|
git annex drop `[path ...]`
|
|
|
|
# DESCRIPTION
|
|
|
|
Drops the content of annexed files from this repository, when
|
|
possible.
|
|
|
|
git-annex will refuse to drop content if it cannot verify it is
|
|
safe to do so. Usually this involves verifying that the content is stored
|
|
in some other repository.
|
|
|
|
Content that is required to be stored in the repository will not be dropped
|
|
even if enough copies exist elsewhere. See [[git-annex-required]](1).
|
|
|
|
With no parameters, tries to drop all annexed files in the current directory.
|
|
Paths of files or directories to drop can be specified.
|
|
|
|
# EXAMPLES
|
|
|
|
# git annex drop *.jpeg
|
|
drop photo1.jpg (checking origin...) ok
|
|
drop photo2.jpg (unsafe)
|
|
Could only verify the existence of 0 out of 1 necessary copies
|
|
|
|
Rather than dropping this file, try using: git annex move
|
|
|
|
(Use --force to override this check, or adjust numcopies.)
|
|
failed
|
|
drop photo3.jpg (checking origin...) ok
|
|
|
|
# OPTIONS
|
|
|
|
* `--from=remote`
|
|
|
|
Rather than dropping the content of files in the local repository,
|
|
this option can specify a remote from which the files'
|
|
contents should be removed.
|
|
|
|
* `--auto`
|
|
|
|
Rather than trying to drop all specified files, drop only those that
|
|
are not preferred content of the repository, and avoid trying to drop
|
|
files when there are not enough other copies for the drop to be possible.
|
|
See [[git-annex-preferred-content]](1)
|
|
|
|
* `--force`
|
|
|
|
Use this option with care! It bypasses safety checks, and forces
|
|
git-annex to delete the content of the specified files, even from
|
|
the last repository that is storing their content. Data loss can
|
|
result from using this option.
|
|
|
|
* `--all` `-A`
|
|
|
|
Rather than specifying a filename or path to drop, this option can be
|
|
used to drop all available versions of all files.
|
|
|
|
This is the default behavior when running git-annex drop in a bare
|
|
repository.
|
|
|
|
Note that this bypasses checking the .gitattributes annex.numcopies
|
|
setting and required content settings.
|
|
|
|
* `--branch=ref`
|
|
|
|
Drop files in the specified branch or treeish.
|
|
|
|
Note that this bypasses checking the .gitattributes annex.numcopies
|
|
setting and required content settings.
|
|
|
|
* `--unused`
|
|
|
|
Drop files found by last run of git-annex unused.
|
|
|
|
Note that this bypasses checking the .gitattributes annex.numcopies
|
|
setting and required content settings.
|
|
|
|
* `--key=keyname`
|
|
|
|
Use this option to drop a specified key.
|
|
|
|
Note that this bypasses checking the .gitattributes annex.numcopies
|
|
setting and required content settings.
|
|
|
|
* matching options
|
|
|
|
The [[git-annex-matching-options]](1)
|
|
can be used to specify what to drop.
|
|
|
|
* `--jobs=N` `-JN`
|
|
|
|
Runs multiple drop jobs in parallel. This is particularly useful
|
|
when git-annex has to contact remotes to check if it can drop files.
|
|
For example: `-J4`
|
|
|
|
Setting this to "cpus" will run one job per CPU core.
|
|
|
|
* `--batch`
|
|
|
|
Enables batch mode, in which lines containing names of files to drop
|
|
are read from stdin.
|
|
|
|
As each specified file is processed, the usual output is
|
|
displayed. If a file's content is not present, or it does not
|
|
match specified matching options, or it is not an annexed file,
|
|
a blank line is output in response instead.
|
|
|
|
* `--batch-keys`
|
|
|
|
This is like `--batch` but the lines read from stdin are parsed as keys.
|
|
|
|
Note that this bypasses checking the .gitattributes annex.numcopies
|
|
setting and required content settings.
|
|
|
|
* `-z`
|
|
|
|
Makes the batch input be delimited by nulls
|
|
instead of the usual newlines.
|
|
|
|
* `--json`
|
|
|
|
Enable JSON output. This is intended to be parsed by programs that use
|
|
git-annex. Each line of output is a JSON object corresponding to a file
|
|
being processed.
|
|
|
|
* `--json-error-messages`
|
|
|
|
Adds an "error-messages" field to the JSON that contains messages that
|
|
would normally be output to the standard error when processing a file.
|
|
|
|
* `--json-exceptions`
|
|
|
|
Output additional JSON objects for some exceptions that are not
|
|
associated with a particular file.
|
|
|
|
* Also the [[git-annex-common-options]](1) can be used.
|
|
|
|
# SEE ALSO
|
|
|
|
[[git-annex]](1)
|
|
|
|
[[git-annex-get]](1)
|
|
|
|
[[git-annex-move]](1)
|
|
|
|
[[git-annex-copy]](1)
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <id@joeyh.name>
|
|
|
|
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
|