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

99 lines
2.6 KiB
Text
Raw Normal View History

separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
# NAME
shorten some too-long descriptions
2019-01-16 18:16:10 +00:00
git-annex info - information about an item or the repository
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
# SYNOPSIS
mention that repo decription can be used
2019-03-28 17:21:37 +00:00
git annex info `[directory|file|treeish|remote|description|uuid ...]`
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
# DESCRIPTION
expand description
2023-11-06 15:11:50 +00:00
Displays statistics and other information for the specified item.
When no item is specified, displays overall information. This includes a
list of all known repositories, how much annexed data is present in the
git-annex log --sizesof This can take a lot of memory. I decided to violate the usual rule in git-annex that it operate in constant memory no matter how many annexed objects. In this case, it would be hard to be fast without using a big map of the location logs. The main difficulty here is that there can be many git-annex branches and it needs to display a consistent view at a point in time, which means merging information from multiple git-annex branches. I have not checked if there are any laziness leaks in this code. It takes 1 gb to run in my big repo, which is around what I estimated before writing it. 2 options that are documented are not yet implemented. Small bug: With eg --when=1h, it will display at 12:00 then 1:10 if the next change after 12:59 is then. Then it waits until after 2:10 to display the next change. It ought to wait until after 2:00. Sponsored-by: Brock Spratlen on Patreon
2023-11-10 20:17:15 +00:00
local repository, and the total size of all annexed data in the working
tree.
expand description
2023-11-06 15:11:50 +00:00
When a directory is specified, displays information
about the annexed files in that directory (and subdirectories).
This includes how much annexed data is present in the local repository,
the total size of all annexed data in the directory, how many files
have the specified numcopies or more (+1, +2 etc) or less (-1, -2 etc),
and information about how much of the annexed data is stored in known
repositories.
When a treeish is specified, displays similar information
as when a directory is specified, but about the annexed files in that
treeish.
When a remote, or description of a repository, or uuid is specified,
displays information about the specified repository, including the total
amount of annexed data stored in it, and a variety of configuration
information.
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
# OPTIONS
* `--fast`
expand description
2023-11-06 15:11:50 +00:00
Only show the information that can be gathered quickly.
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
* `--json`
finished splitting out man pages for all commands
2015-03-25 16:09:49 +00:00
Enable JSON output. This is intended to be parsed by programs that use
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
git-annex. Each line of output is a JSON object.
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
add --json-error-messages (not yet implemented) Added --json-error-messages option, which includes error messages in the json output, rather than outputting them to stderr. The actual rediretion of errors is not implemented yet, this is only the docs and option plumbing. This commit was supported by the NSF-funded DataLad project.
2018-02-19 18:28:17 +00:00
* `--json-error-messages`
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.
add --json-error-messages (not yet implemented) Added --json-error-messages option, which includes error messages in the json output, rather than outputting them to stderr. The actual rediretion of errors is not implemented yet, this is only the docs and option plumbing. This commit was supported by the NSF-funded DataLad project.
2018-02-19 18:28:17 +00:00
info: Added --bytes option.
2015-04-12 18:08:40 +00:00
* `--bytes`
Show file sizes in bytes, disabling the default nicer units.
info: Support --batch mode.
2016-01-15 19:56:47 +00:00
* `--batch`
Enable batch mode, in which a line containing an item is read from stdin,
the information about it is output to stdout, and repeat.
added -z Added -z option to git-annex commands that use --batch, useful for supporting filenames containing newlines. It only controls input to --batch, the output will still be line delimited unless --json or etc is used to get some other output. While git often makes -z affect both input and output, I don't like trying them together, and making it affect output would have been a significant complication, and also git-annex output is generally not intended to be machine parsed, unless using --json or a format option. Commands that take pairs like "file key" still separate them with a space in --batch mode. All such commands take care to support filenames with spaces when parsing that, so there was no need to change it, and it would have needed significant changes to the batch machinery to separate tose with a null. To make fromkey and registerurl support -z, I had to give them a --batch option. The implicit batch mode they enter when not provided with input parameters does not support -z as that would have complicated option parsing. Seemed better to move these toward using the same --batch as everything else, though the implicit batch mode can still be used. This commit was sponsored by Ole-Morten Duesund on Patreon.
2018-09-20 20:09:21 +00:00
* `-z`
Makes the `--batch` input be delimited by nulls instead of the usual
newlines.
info: Added --autoenable option Use cases include using git-annex init --no-autoenable and then going back and enabling the special remotes that have autoenable configured. As well as just querying to remember which ones have it enabled. It lists all special remotes that have autoenable=yes whether currently enabled or not. And it can be used with --json. I pondered making this "git-annex info autoenable", but that seemed wrong because then if the use has a directory named "autoenable", it's unclear what they are asking for. (Although "git-annex info remote" may be similarly unclear.) Making it an option does mean that it can't be provided via --batch though. Sponsored-by: Dartmouth College's Datalad project
2022-06-01 18:20:38 +00:00
* `--autoenable`
Display a list of special remotes that have been configured to
autoenable.
info: Added --dead-repositories option I considered a more wide-ranging config option to make other commands also show dead repositories. But it would be difficult to implement that because Remote.keyLocations is used to get locations, filtering out dead repos, and commands like get then try to use those locations. So a config setting would make dead repos sometimes be acted on by commands. Sponsored-by: unqueued on Patreon
2023-08-09 16:43:48 +00:00
* `--dead-repositories`
Display a list of repositories that have been marked as dead.
Such repositories are not displayed in other info displays.
info: Allow using matching options in more situations File matching options like --include will be rejected in situations where there is no filename to match against. (Or where there is a filename but it's not relative to the cwd, or otherwise seemed too bothersome to match against.) The addition of listKeys' was necessary to avoid using more memory in the common case of "git-annex info". Adding a filterM would have caused the list to buffer in memory and not stream. This is an ugly hack, but listKeys had previously run Annex operations inside unafeInterleaveIO (for direct mode). And matching against a matcher should hopefully not change any Annex state. This does allow for eg `git-annex info somefile --include=*.ext` although why someone would want to do that I don't really know. But it seems to make sense to allow it. But, consider: `git-annex info ./somefile --include=somefile` This does not match, so will not display info about somefile. If the user really wants to, they can `--include=./somefile`. Using matching options like --copies or --in=remote seems likely to be slower than git-annex find with those options, because unlike such commands, info does not have optimised streaming through the matcher. Note that `git-annex info remote` is not the same as `git-annex info --in remote`. The former shows info about all files in the remote. The latter shows local keys that are also in that remote. The output should make that clear, but this still seems like a point where users could get confused. Sponsored-by: Jochen Bartl on Patreon
2022-02-21 18:45:11 +00:00
* matching options
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
info: Allow using matching options in more situations File matching options like --include will be rejected in situations where there is no filename to match against. (Or where there is a filename but it's not relative to the cwd, or otherwise seemed too bothersome to match against.) The addition of listKeys' was necessary to avoid using more memory in the common case of "git-annex info". Adding a filterM would have caused the list to buffer in memory and not stream. This is an ugly hack, but listKeys had previously run Annex operations inside unafeInterleaveIO (for direct mode). And matching against a matcher should hopefully not change any Annex state. This does allow for eg `git-annex info somefile --include=*.ext` although why someone would want to do that I don't really know. But it seems to make sense to allow it. But, consider: `git-annex info ./somefile --include=somefile` This does not match, so will not display info about somefile. If the user really wants to, they can `--include=./somefile`. Using matching options like --copies or --in=remote seems likely to be slower than git-annex find with those options, because unlike such commands, info does not have optimised streaming through the matcher. Note that `git-annex info remote` is not the same as `git-annex info --in remote`. The former shows info about all files in the remote. The latter shows local keys that are also in that remote. The output should make that clear, but this still seems like a point where users could get confused. Sponsored-by: Jochen Bartl on Patreon
2022-02-21 18:45:11 +00:00
The [[git-annex-matching-options]](1) can be used to select what
to include in the statistics.
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
split out common options to its own page and mention it on each subcommand page Sometimes users would get confused because an option they were looking for was not mentioned on a subcommand's man page, and they had not noticed that the main git-annex man page had a list of common options. This change lets each subcommand mention the common options, similarly to how the matching options are handled. This commit was sponsored by Svenne Krap on Patreon.
2021-05-10 19:00:13 +00:00
* Also the [[git-annex-common-options]](1) can be used.
separated man pages for all the maintenance commands
2015-03-24 19:23:59 +00:00
# EXAMPLES
Suppose you want to run "git annex get .", but
would first like to see how much disk space that will use.
Then run:
git annex info --fast . --not --in here
# SEE ALSO
[[git-annex]](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