mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
git-annex/doc/git-annex-findkeys.mdwn

76 lines
1.9 KiB
Text
Raw Normal View History

findkeys: New command, very similar to git-annex find but operating on keys I've long been asked for `git-annex find --all` or something like that, but pushed back on it because I feel that the command is analagous to find(1) and so it would be surprising for it to list keys rather than files. So instead, add a new findkeys subcommand. Note that the use of withKeyOptions is rather strange because usually that is used to fall back to --all rather than listing files, but here it's made to default to --all like behavior and never list files. A performance thing that could be improved is that withKeyOptions always reads and caches location logs. But findkeys with no options does not need them, so it could be made faster. That caching does speed up options like --in though. This is really just a subset of a more general performance thing that --all reads location logs sometimes unncessarily. Anyway, it needs to read the location log in order to checkDead, and it seems good that findkeys does skip dead keys. Also, cleaned up comments on git-annex-find man page asking for --all option. Sponsored-by: Dartmouth College's DANDI project
2023-01-17 18:42:29 +00:00
# NAME
git-annex findkeys - lists available keys
# SYNOPSIS
git annex findkeys
# DESCRIPTION
Outputs a list of keys known to git-annex.
# OPTIONS
* matching options
The [[git-annex-matching-options]](1)
can be used to specify which keys to list.
By default, the findkeys command only lists keys whose content is
currently present. Specifying any of the matching options will override
this default behavior and match on all keys that git-annex knows about.
To list all keys, present or not, specify `--anything`.
To list keys whose content is not present, specify `--not --in=here`
* `--print0`
Output keys terminated with nulls, for use with `xargs -0`
* `--format=value`
Use custom output formatting.
The value is a format string, in which '${var}' is expanded to the
value of a variable. To right-justify a variable with whitespace,
use '${var;width}' ; to left-justify a variable, use '${var;-width}';
mention control characters
2023-04-11 18:06:46 +00:00
to escape unusual characters (including control characters)
in a variable, use '${escaped_var}'
findkeys: New command, very similar to git-annex find but operating on keys I've long been asked for `git-annex find --all` or something like that, but pushed back on it because I feel that the command is analagous to find(1) and so it would be surprising for it to list keys rather than files. So instead, add a new findkeys subcommand. Note that the use of withKeyOptions is rather strange because usually that is used to fall back to --all rather than listing files, but here it's made to default to --all like behavior and never list files. A performance thing that could be improved is that withKeyOptions always reads and caches location logs. But findkeys with no options does not need them, so it could be made faster. That caching does speed up options like --in though. This is really just a subset of a more general performance thing that --all reads location logs sometimes unncessarily. Anyway, it needs to read the location log in order to checkDead, and it seems good that findkeys does skip dead keys. Also, cleaned up comments on git-annex-find man page asking for --all option. Sponsored-by: Dartmouth College's DANDI project
2023-01-17 18:42:29 +00:00
These variables are available for use in formats: key, backend,
bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for
the mtime field of a WORM key).
Also, '\\n' is a newline, '\\000' is a NULL, etc.
find, findkeys, examinekey: escape output to terminal when --format is not used Note that filenames are not quoted, only escaped. This is to match the output of --format with escaping. Sponsored-by: Lawrence Brogan on Patreon
2023-04-11 18:57:09 +00:00
The default output format is the same as `--format='${escapedkey}\\n'`
avoid quoting spaces in git-annex find output to terminal That's too much quoting, the user expects the filename to be copy and pasteable. It would be ok to slash-escape space ('\ ') which is what gnu find does, but it doesn't seem necessary either. ${escaped_file} has always quoted spaces though, so keep on doing it there. Sponsored-by: Nicholas Golder-Manning on Patreon
2023-04-26 04:12:38 +00:00
except when outputting to a terminal, control characters will be escaped.
findkeys: New command, very similar to git-annex find but operating on keys I've long been asked for `git-annex find --all` or something like that, but pushed back on it because I feel that the command is analagous to find(1) and so it would be surprising for it to list keys rather than files. So instead, add a new findkeys subcommand. Note that the use of withKeyOptions is rather strange because usually that is used to fall back to --all rather than listing files, but here it's made to default to --all like behavior and never list files. A performance thing that could be improved is that withKeyOptions always reads and caches location logs. But findkeys with no options does not need them, so it could be made faster. That caching does speed up options like --in though. This is really just a subset of a more general performance thing that --all reads location logs sometimes unncessarily. Anyway, it needs to read the location log in order to checkDead, and it seems good that findkeys does skip dead keys. Also, cleaned up comments on git-annex-find man page asking for --all option. Sponsored-by: Dartmouth College's DANDI project
2023-01-17 18:42:29 +00:00
* `--json`
Revert "--json-exceptions" This reverts commit a325524454fdc45a61f91844efb3065f6e34b318. Turns out this was predicated on an incorrect belief that json output didn't already sometimes lack the "key" field. Since json output already can when `giveup` was used, it seems unncessary to add a whole new option for this.
2023-04-25 21:37:34 +00:00
Output the list of keys in JSON format.
findkeys: New command, very similar to git-annex find but operating on keys I've long been asked for `git-annex find --all` or something like that, but pushed back on it because I feel that the command is analagous to find(1) and so it would be surprising for it to list keys rather than files. So instead, add a new findkeys subcommand. Note that the use of withKeyOptions is rather strange because usually that is used to fall back to --all rather than listing files, but here it's made to default to --all like behavior and never list files. A performance thing that could be improved is that withKeyOptions always reads and caches location logs. But findkeys with no options does not need them, so it could be made faster. That caching does speed up options like --in though. This is really just a subset of a more general performance thing that --all reads location logs sometimes unncessarily. Anyway, it needs to read the location log in order to checkDead, and it seems good that findkeys does skip dead keys. Also, cleaned up comments on git-annex-find man page asking for --all option. Sponsored-by: Dartmouth College's DANDI project
2023-01-17 18:42:29 +00:00
Revert "--json-exceptions" This reverts commit a325524454fdc45a61f91844efb3065f6e34b318. Turns out this was predicated on an incorrect belief that json output didn't already sometimes lack the "key" field. Since json output already can when `giveup` was used, it seems unncessary to add a whole new option for this.
2023-04-25 21:37:34 +00:00
This is intended to be parsed by programs that use
git-annex. Each line of output is a JSON object.
--json-exceptions 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
2023-04-25 21:02:25 +00:00
Revert "--json-exceptions" This reverts commit a325524454fdc45a61f91844efb3065f6e34b318. Turns out this was predicated on an incorrect belief that json output didn't already sometimes lack the "key" field. Since json output already can when `giveup` was used, it seems unncessary to add a whole new option for this.
2023-04-25 21:37:34 +00:00
* `--json-error-messages`
--json-exceptions 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
2023-04-25 21:02:25 +00:00
Revert "--json-exceptions" This reverts commit a325524454fdc45a61f91844efb3065f6e34b318. Turns out this was predicated on an incorrect belief that json output didn't already sometimes lack the "key" field. Since json output already can when `giveup` was used, it seems unncessary to add a whole new option for this.
2023-04-25 21:37:34 +00:00
Messages that would normally be output to standard error are included in
the JSON instead.
findkeys: New command, very similar to git-annex find but operating on keys I've long been asked for `git-annex find --all` or something like that, but pushed back on it because I feel that the command is analagous to find(1) and so it would be surprising for it to list keys rather than files. So instead, add a new findkeys subcommand. Note that the use of withKeyOptions is rather strange because usually that is used to fall back to --all rather than listing files, but here it's made to default to --all like behavior and never list files. A performance thing that could be improved is that withKeyOptions always reads and caches location logs. But findkeys with no options does not need them, so it could be made faster. That caching does speed up options like --in though. This is really just a subset of a more general performance thing that --all reads location logs sometimes unncessarily. Anyway, it needs to read the location log in order to checkDead, and it seems good that findkeys does skip dead keys. Also, cleaned up comments on git-annex-find man page asking for --all option. Sponsored-by: Dartmouth College's DANDI project
2023-01-17 18:42:29 +00:00
* Also the [[git-annex-common-options]](1) can be used.
# SEE ALSO
[[git-annex]](1)
[[git-annex-find]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
Reference in a new issue Copy permalink