mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

separated man pages for all the maintenance commands

Browse source
This commit is contained in:
Joey Hess 2015-03-24 15:23:59 -04:00
parent f10282807e
commit 0850e8eaf9
17 changed files with 678 additions and 132 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
doc/git-annex-addunused.mdwn Normal file
View file

@ -0,0 +1,24 @@
# NAME
git-annex addunused - add back unused files
# SYNOPSIS
git annex addunused `[number|range ...]`
# DESCRIPTION
Adds back files for the content corresponding to the numbers or ranges,
as listed by the last `git annex unused`.
The files will have names starting with "unused."
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

39
doc/git-annex-dropunused.mdwn Normal file
View file

@ -0,0 +1,39 @@
# NAME
git-annex dropunused - drop unused file content
# SYNOPSIS
git annex dropunused `[number|range ...]`
# DESCRIPTION
Drops the data corresponding to the numbers, as listed by the last
git annex unused`
You can also specify ranges of numbers, such as "1-1000".
Or, specify "all" to drop all unused data.
# OPTIONS
* `--from=remote`
Rather than dropping the unused files from the local repository,
drop them from the remote repository.
* `--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.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

55
doc/git-annex-find.mdwn Normal file
View file

@ -0,0 +1,55 @@
# NAME
git-annex find - lists available files
# SYNOPSIS
git annex find `[path ...]`
# DESCRIPTION
Outputs a list of annexed files in the specified path. With no path,
finds files in the current directory and its subdirectories.
# OPTIONS
* `--print0`
Output filenames terminated with nulls, for use with `xargs -0`
* `--format=fmt`
Use custom output formatting.
The default output format is the same as `--format='${file}\\n'`
These variables are available for use in formats: file, key, backend,
bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for
the mtime field of a WORM key).
* `--json`
Output the list of files in JSON format.
* matching options
The [[git-annex-matching-options]](1)
can be used to specify files to list.
By default, the find command only lists annexed files whose content is
currently present. Specifying any of the matching options will override
this default behavior.
To list all annexed files, present or not, specify `--include "*"`.
To list annexed files whose content is not present, specify `--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.

32
doc/git-annex-fix.mdwn Normal file
View file

@ -0,0 +1,32 @@
# NAME
git-annex fix - fix up symlinks to point to annexed content
# SYNOPSIS
git annex fix `[path ...]`
# DESCRIPTION
Fixes up symlinks that have become broken to again point to annexed
content.
This is useful to run if you have been moving the symlinks around,
but is done automatically when committing a change with git too.
# OPTIONS
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to fix.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

37
doc/git-annex-forget.mdwn Normal file
View file

@ -0,0 +1,37 @@
# NAME
git-annex forget - prune git-annex branch history
# SYNOPSIS
git annex forget
# DESCRIPTION
Causes the git-annex branch to be rewritten, throwing away historical
data about past locations of files. The resulting branch will use less
space, but `git annex log` will not be able to show where
files used to be located.
When this rewritten branch is merged into other clones of
the repository, `git-annex` will automatically perform the same rewriting
to their local `git-annex` branches. So the forgetfulness will automatically
propagate out from its starting point until all repositories running
git-annex have forgotten their old history. (You may need to force
git to push the branch to any git repositories not running git-annex.)
# OPTIONS
* `--drop-dead`
Also prune references to repositories that have been marked as dead.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

91
doc/git-annex-fsck.mdwn Normal file
View file

@ -0,0 +1,91 @@
# NAME
git-annex fsck - check for problems
# SYNOPSIS
git annex fsck `[path ...]`
# DESCRIPTION
With no parameters, this command checks the whole annex for consistency,
and warns about or fixes any problems found. This is a good complement to
`git fsck`.
With parameters, only the specified files are checked.
# OPTIONS
* `--from=remote`
Check a remote, rather than the local repository.
Note that by default, files will be copied from the remote to check
their contents. To avoid this expensive transfer, and only
verify that the remote still has the files that are expected to be on it,
add the `--fast` option.
* `--fast`
Avoids expensive checksum calculations (and expensive transfers when
fscking a remote).
* `--incremental`
Start a new incremental fsck pass. An incremental fsck can be interrupted
at any time, with eg ctrl-c.
* `--more`
Continue the last incremental fsck pass, where it left off.
* `--incremental-schedule=time`
This makes a new incremental fsck be started only a specified
time period after the last incremental fsck was started.
The time is in the form "10d" or "300h".
Maybe you'd like to run a fsck for 5 hours at night, picking up each
night where it left off. You'd like this to continue until all files
have been fscked. And once it's done, you'd like a new fsck pass to start,
but no more often than once a month. Then put this in a nightly cron job:
git annex fsck --incremental-schedule 30d --time-limit 5h
* `--numcopies=N`
Override the normally configured number of copies.
To verify data integrity only while disregarding required number of copies,
use `--numcopies=1`.
* `--all`
Normally only the files in the currently checked out branch
are fscked. This option causes all versions of all files to be fscked.
* `--unused`
Operate on files found by last run of git-annex unused.
* `--key=keyname`
Use this option to fsck a specified key.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to fsck.
# OPTIONS
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

4
doc/git-annex-get.mdwn
View file

@ -24,6 +24,10 @@ or transferring them from some kind of key-value store.
Rather than specifying a filename or path to get, this option can be Rather than specifying a filename or path to get, this option can be
used to get all available versions of all files. used to get all available versions of all files.
* `--unused`
Operate on files found by last run of git-annex unused.
* `--key=keyname` * `--key=keyname`
Use this option to get a specified key. Use this option to get a specified key.

50
doc/git-annex-info.mdwn Normal file
View file

@ -0,0 +1,50 @@
# NAME
git-annex info - shows information about the specified item or the repository as a whole
# SYNOPSIS
git annex info `[directory|file|remote|uuid ...]`
# DESCRIPTION
Displays statistics and other information for the specified item,
which can be a directory, or a file, or a remote, or the uuid of a
repository.
When no item is specified, displays statistics and information
for the repository as a whole.
# OPTIONS
* `--fast`
Only show the data that can be gathered quickly.
* `--json`
Enable JSON output.
* file matching options
When a directory is specified, the [[git-annex-matching-options]](1)
can be used to select the files in the directory that are included
in the statistics.
# 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.

34
doc/git-annex-list.mdwn Normal file
View file

@ -0,0 +1,34 @@
# NAME
git-annex list - show which remotes contain files
# SYNOPSIS
git annex list `[path ...]`
# DESCRIPTION
Displays a table of remotes that contain the contents of the specified
files. This is similar to `git annex whereis` but a more compact display.
# OPTIONS
* `--allrepos`
Only configured remotes are shown by default; this option
adds all known repositories to the list.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to list.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

42
doc/git-annex-log.mdwn Normal file
View file

@ -0,0 +1,42 @@
# NAME
git-annex log - shows location log
# SYNOPSIS
git annex log `[path ...]`
# DESCRIPTION
Displays the location log for the specified file or files,
showing each repository they were added to ("+") and removed from ("-").
# OPTIONS
* `--since=date`, `--after=date`, `--until=date`, `--before=date`, `--max-count=N`
These options are passed through to `git log`, and can be used to limit
how far back to search for location log changes.
For example: `--since "1 month ago"`
* `--gource`
Generates output suitable for the `gource` visualization program.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to act on.
# OPTIONS
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

40
doc/git-annex-map.mdwn Normal file
View file

@ -0,0 +1,40 @@
# NAME
git-annex map - generate map of repositories
# SYNOPSIS
git annex map
# DESCRIPTION
Helps you keep track of your repositories, and the connections between them,
by going out and looking at all the ones it can get to, and generating a
Graphviz file displaying it all. If the `dot` command is available, it is
used to display the file to your screen (using x11 backend).
This command only connects to hosts that the host it's run on can
directly connect to. It does not try to tunnel through intermediate hosts.
So it might not show all connections between the repositories in the network
Also, if connecting to a host requires a password, you might have to enter
it several times as the map is being built.
Note that this subcommand can be used to graph any git repository; it
is not limited to git-annex repositories.
# OPTIONS
* `--fast`
Disable using `dot` to display the generated Graphviz file.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

55
doc/git-annex-repair.mdwn Normal file
View file

@ -0,0 +1,55 @@
# NAME
git-annex repair - recover broken git repository
# SYNOPSIS
git annex repair
# DESCRIPTION
This can repair many of the problems with git repositories that `git fsck`
detects, but does not itself fix. It's useful if a repository has become
badly damaged. One way this can happen is if a repository used by git-annex
is on a removable drive that gets unplugged at the wrong time.
This command can actually be used inside git repositories that do not
use git-annex at all; when used in a repository using git-annex, it
does additional repairs of the git-annex branch.
It works by deleting any corrupt objects from the git repository, and
retrieving all missing objects it can from the remotes of the repository.
If that is not sufficient to fully recover the repository, it can also
reset branches back to commits before the corruption happened, delete
branches that are no longer available due to the lost data, and remove any
missing files from the index. It will only do this if run with the
`--force` option, since that rewrites history and throws out missing data.
Note that the `--force` option never touches tags, even if they are no
longer usable due to missing data.
After running this command, you will probably want to run `git fsck` to
verify it fixed the repository. Note that fsck may still complain about
objects referenced by the reflog, or the stash, if they were unable to be
recovered. This command does not try to clean up either the reflog or the
stash.
It is also a good idea to run `git annex fsck --fast` after this command,
to make sure that the git-annex branch reflects reality.
# OPTIONS
* `--force`
Enable repair actions that involve deleting data that has been
lost due to git repository corruption.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

39
doc/git-annex-unused.mdwn Normal file
View file

@ -0,0 +1,39 @@
# NAME
git-annex unused - look for unused file content
# SYNOPSIS
git annex unused
# DESCRIPTION
Checks the annex for data that does not correspond to any files present
in any tag or branch, and prints a numbered list of the data.
After running this command, you can use the `--unused` option with many
other git-annex commands to operate on all the unused data that was found.
For example, to move all unused data to origin:
git annex unused; git annex move --unused --to origin
# OPTIONS
* `--fast`
Only show unused temp and bad files.
* `--from=remote`
Check for unused data on a remote.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

32
doc/git-annex-upgrade.mdwn Normal file
View file

@ -0,0 +1,32 @@
# NAME
git-annex upgrade - upgrade repository layout
# SYNOPSIS
git annex upgrade
# DESCRIPTION
Upgrades the repository to current layout.
Each git-annex repository has an annex.version in its git configuration,
that indicates the repository version. If git-annex changes to a new
layout, you must upgrade the repository before git-annex can be used in it.
To see version information, run `git annex version`.
Currently, git-annex supports upgrades all the way back to version 0, which
was only used by its author. It's expected that git-annex will always
support upgrading from all past repository versions -- this is necessary to
allow archives to be taken offline for years and later used.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

30
doc/git-annex-version.mdwn Normal file
View file

@ -0,0 +1,30 @@
# NAME
git-annex version - show version info
# SYNOPSIS
git annex version
# DESCRIPTION
Shows the version of git-annex, as well as repository version information.
git-annex's version is in the form MAJOR.DATE, where MAJOR is a number
like 5, which corresponds to the current repository version, and DATE
is the date of the last release, like 20150320.
Daily builds of git-annex will append a "-gREF" to the version, which
corresponds to the git ref from git-annex's source repository that was
built. Therefore, "5.20150320-gdd35cf3" is a daily build, and
"5.20150401" is an April 1st release made a bit later.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

42
doc/git-annex-whereis.mdwn Normal file
View file

@ -0,0 +1,42 @@
# NAME
git-annex whereis - lists repositories that have file content
# SYNOPSIS
git annex whereis `[path ...]`
# DESCRIPTION
Displays information about where the contents of files are located.
For example:
# git annex whereis
whereis my_cool_big_file (1 copy)
0c443de8-e644-11df-acbf-f7cd7ca6210d -- laptop
whereis other_file (3 copies)
0c443de8-e644-11df-acbf-f7cd7ca6210d -- laptop
62b39bbe-4149-11e0-af01-bb89245a1e61 -- usb drive [here]
7570b02e-15e9-11e0-adf0-9f3f94cb2eaa -- backup drive
# OPTIONS
* `--json`
Enable JSON output format.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to act on.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

154
doc/git-annex.mdwn
View file

@ -297,73 +297,37 @@ subdirectories).
* `fsck [path ...]` * `fsck [path ...]`
With no parameters, this command checks the whole annex for consistency, Checks the annex consistency, and warns about or fixes any problems found.
and warns about or fixes any problems found. This is a good complement to This is a good complement to `git fsck`.
`git fsck`.
With parameters, only the specified files are checked. See [[git-annex-fsck]](1) for details.
To check a remote to fsck, specify `--from`.
To avoid expensive checksum calculations (and expensive transfers when
fscking a remote), specify `--fast`.
To start a new incremental fsck, use the `--incremental` option. Then
the next time you fsck, you can instead use the `--more` option
to skip over files that have already been checked, and continue
where it left off.
The `--incremental-schedule` option makes a new incremental fsck be
started a configurable time after the last incremental fsck was started.
Once the current incremental fsck has completely finished, it causes
a new one to start.
Maybe you'd like to run a fsck for 5 hours at night, picking up each
night where it left off. You'd like this to continue until all files
have been fscked. And once it's done, you'd like a new fsck pass to start,
but no more often than once a month. Then put this in a nightly cron job:
git annex fsck --incremental-schedule 30d --time-limit 5h
To verify data integrity only while disregarding required number of copies,
use `--numcopies=1`.
* `unused` * `unused`
Checks the annex for data that does not correspond to any files present Checks the annex for data that does not correspond to any files present
in any tag or branch, and prints a numbered list of the data. in any tag or branch, and prints a numbered list of the data.
To only show unused temp and bad files, specify `--fast`. See [[git-annex-unused]](1) for details.
To check for annexed data on a remote, specify `--from`.
After running this command, you can use the `--unused` option to
operate on all the unused data that was found. For example, to
move all unused data to origin:
git annex unused; git annex move --unused --to origin
* `dropunused [number|range ...]` * `dropunused [number|range ...]`
Drops the data corresponding to the numbers, as listed by the last Drops the data corresponding to the numbers, as listed by the last
`git annex unused` `git annex unused`
You can also specify ranges of numbers, such as "1-1000". See [[git-annex-dropunused]](1) for details.
Or, specify "all" to drop all unused data.
To drop the data from a remote, specify `--from.`
* `addunused [number|range ...]` * `addunused [number|range ...]`
Adds back files for the content corresponding to the numbers or ranges, Adds back files for the content corresponding to the numbers or ranges,
as listed by the last `git annex unused`. The files will have names as listed by the last `git annex unused`.
starting with "unused."
See [[git-annex-addunused]](1) for details.
* `fix [path ...]` * `fix [path ...]`
Fixes up symlinks that have become broken to again point to annexed content. Fixes up symlinks that have become broken to again point to annexed content.
This is useful to run if you have been moving the symlinks around,
but is done automatically when committing a change with git too. See [[git-annex-fix]](1) for details.
* `merge` * `merge`
@ -375,22 +339,14 @@ subdirectories).
Upgrades the repository to current layout. Upgrades the repository to current layout.
See [[git-annex-upgrade]](1) for details.
* `forget` * `forget`
Causes the git-annex branch to be rewritten, throwing away historical Causes the git-annex branch to be rewritten, throwing away historical
data about past locations of files. The resulting branch will use less data about past locations of files.
space, but `git annex log` will not be able to show where
files used to be located.
To also prune references to repositories that have been marked as dead, See [[git-annex-forget]](1) for details.
specify `--drop-dead`.
When this rewritten branch is merged into other clones of
the repository, `git-annex` will automatically perform the same rewriting
to their local `git-annex` branches. So the forgetfulness will automatically
propagate out from its starting point until all repositories running
git-annex have forgotten their old history. (You may need to force
git to push the branch to any git repositories not running git-annex.)
* `repair` * `repair`
@ -399,29 +355,7 @@ subdirectories).
badly damaged. One way this can happen is if a repository used by git-annex badly damaged. One way this can happen is if a repository used by git-annex
is on a removable drive that gets unplugged at the wrong time. is on a removable drive that gets unplugged at the wrong time.
This command can actually be used inside git repositories that do not See [[git-annex-repair]](1) for details.
use git-annex at all; when used in a repository using git-annex, it
does additional repairs of the git-annex branch.
It works by deleting any corrupt objects from the git repository, and
retrieving all missing objects it can from the remotes of the repository.
If that is not sufficient to fully recover the repository, it can also
reset branches back to commits before the corruption happened, delete
branches that are no longer available due to the lost data, and remove any
missing files from the index. It will only do this if run with the
`--force` option, since that rewrites history and throws out missing data.
Note that the `--force` option never touches tags, even if they are no
longer usable due to missing data.
After running this command, you will probably want to run `git fsck` to
verify it fixed the repository. Note that fsck may still complain about
objects referenced by the reflog, or the stash, if they were unable to be
recovered. This command does not try to clean up either the reflog or the
stash.
It is also a good idea to run `git annex fsck --fast` after this command,
to make sure that the git-annex branch reflects reality.
# QUERY COMMANDS # QUERY COMMANDS
@ -430,41 +364,27 @@ subdirectories).
Outputs a list of annexed files in the specified path. With no path, Outputs a list of annexed files in the specified path. With no path,
finds files in the current directory and its subdirectories. finds files in the current directory and its subdirectories.
By default, only lists annexed files whose content is currently present. See [[git-annex-find]](1) for details.
This can be changed by specifying [[git-annex-matching-options]](1).
To list all annexed files, present or not, specify `--include "*"`. To list all
annexed files whose content is not present, specify `--not --in=here`
To output filenames terminated with nulls, for use with xargs -0,
specify `--print0`. Or, a custom output formatting can be specified using
`--format`. The default output format is the same as `--format='${file}\\n'`
These variables are available for use in formats: file, key, backend,
bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for
the mtime field of a WORM key).
* `whereis [path ...]` * `whereis [path ...]`
Displays information about where the contents of files are located. Displays information about where the contents of files are located.
See [[git-annex-whereis]](1) for details.
* `list [path ...]` * `list [path ...]`
Displays a table of remotes that contain the contents of the specified Displays a table of remotes that contain the contents of the specified
files. This is similar to whereis but a more compact display. Only files. This is similar to whereis but a more compact display.
configured remotes are shown by default; specify --allrepos to list
all repositories. See [[git-annex-list]](1) for details.
* `log [path ...]` * `log [path ...]`
Displays the location log for the specified file or files, Displays the location log for the specified file or files,
showing each repository they were added to ("+") and removed from ("-"). showing each repository they were added to ("+") and removed from ("-").
To limit how far back to search for location log changes, the options See [[git-annex-log]](1) for details.
`--since`, `--after`, `--until`, `--before`, and `--max-count` can be specified.
They are passed through to git log. For example, `--since "1 month ago"`
To generate output suitable for the gource visualization program,
specify `--gource`.
* `info [directory|file|remote|uuid ...]` * `info [directory|file|remote|uuid ...]`
@ -475,39 +395,19 @@ subdirectories).
When no item is specified, displays statistics and information When no item is specified, displays statistics and information
for the repository as a whole. for the repository as a whole.
When a directory is specified, the [[git-annex-matching-options]](1) See [[git-annex-info]](1) for details.
can be used to select the files in the directory that are included
in the statistics.
To only show the data that can be gathered quickly, use `--fast`.
For example, 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
* `version` * `version`
Shows the version of git-annex, as well as repository version information. Shows the version of git-annex, as well as repository version information.
See [[git-annex-version]](1) for details.
* `map` * `map`
Helps you keep track of your repositories, and the connections between them, Generate map of repositories.
by going out and looking at all the ones it can get to, and generating a
Graphviz file displaying it all. If the `dot` command is available, it is
used to display the file to your screen (using x11 backend). (To disable
this display, specify `--fast`)
This command only connects to hosts that the host it's run on can See [[git-annex-map]](1) for details.
directly connect to. It does not try to tunnel through intermediate hosts.
So it might not show all connections between the repositories in the network.
Also, if connecting to a host requires a password, you might have to enter
it several times as the map is being built.
Note that this subcommand can be used to graph any git repository; it
is not limited to git-annex repositories.
# METADATA COMMANDS # METADATA COMMANDS