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

splitting up the man page

Browse source 
Common command man pages all split out and often expanded.

A few sections split out into their own pages.

Still need to do all the other commands..
This commit is contained in:
Joey Hess 2015-03-23 15:36:10 -04:00
parent 5c2ad84d28
commit daec4b007a
28 changed files with 1204 additions and 447 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Command/Assistant.hs
View file

@ -22,7 +22,7 @@ import System.Environment
cmd :: [Command]
cmd = [noRepo checkAutoStart $ dontCheck repoExists $ withOptions options $
notBareRepo $ command "assistant" paramNothing seek SectionCommon
"automatically handle changes"]
"automatically sync changes"]
options :: [Option]
options =

2
Command/Watch.hs
View file

@ -14,7 +14,7 @@ import Utility.HumanTime
cmd :: [Command]
cmd = [notBareRepo $ withOptions [foregroundOption, stopOption] $
command "watch" paramNothing seek SectionCommon "watch for changes"]
command "watch" paramNothing seek SectionCommon "watch for changes and autocommit"]
seek :: CommandSeek
seek ps = do

6
Makefile
View file

@ -1,4 +1,4 @@
mans=git-annex.1 git-annex-shell.1
mans=git-annex.1 $(shell find doc -maxdepth 1 -name git-annex-*.mdwn | sed -e 's/doc\///' -e 's/\.mdwn/\.1/')
all=git-annex $(mans) docs
CABAL?=cabal # set to "./Setup" if you lack a cabal program
@ -67,7 +67,9 @@ else
IKIWIKI=ikiwiki
endif
docs: $(mans)
mans: $(mans)
docs: mans
$(IKIWIKI) doc html -v --wikiname git-annex --plugin=goodstuff \
--no-usedirs --disable-plugin=openid --plugin=sidebar \
--underlaydir=/dev/null --disable-plugin=shortcut \

47
doc/git-annex-add.mdwn Normal file
View file

@ -0,0 +1,47 @@
# NAME
git-annex add - adds files to the git annex
# SYNOPSIS
git annex add `[path ...]`
# DESCRIPTION
Adds files in the path to the annex. If no path is specified, adds
files from the current directory and below.
Normally, files that are already checked into git, or that git has been
configured to ignore will be silently skipped.
# OPTIONS
* `--include-dotfiles`
Dotfiles are skipped unless explicitly listed, or unless this option is
used.
* `--force`
Add gitignored files.
* `--backend`
Specifies which key-value backend to use.
* file matching options
Many of the [[git-annex-matching-options]](1)
can be used to specify files to add.
For example: `--largerthan=1GB`
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

66
doc/git-annex-addurl.mdwn Normal file
View file

@ -0,0 +1,66 @@
# NAME
git-annex addurl - add urls to annex
# SYNOPSIS
git annex addurl `[url ...]`
# DESCRIPTION
Downloads each url to its own file, which is added to the annex.
When `quvi` is installed, urls are automatically tested to see if they
point to a video hosting site, and the video is downloaded instead.
Urls to torrent files (including magnet links) will cause the content of
the torrent to be downloaded, using `aria2c`.
Normally the filename is based on the full url, so will look like
"www.example.com_dir_subdir_bigfile". In some cases, addurl is able to
come up with a better filename based on other information. Options can also
be used to get better filenames.
# OPTIONS
* `--fast`
Avoid immediately downloading the url.
* `--relaxed`
Avoid storing the size of the url's content, and accept whatever
content is there at a future point. (Implies `--fast`.)
* `--raw`
Prevent special handling of urls by quvi, bittorrent, and other
special remotes. This will for example, make addurl
download the .torrent file and not the contents it points to.
* `--file=name`
Use with a filename that does not yet exist to add a new file
with the specified name and the content downloaded from the url.
If the file already exists, addurl will record that it can be downloaded
from the specified url(s).
* `--pathdepth=N`
This causes a shorter filename to be used. For example,
`--pathdepth=1` will use "dir/subdir/bigfile",
while `--pathdepth=3` will use "bigfile".
It can also be negative; `--pathdepth=-2` will use the last
two parts of the url.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

47
doc/git-annex-assistant.mdwn Normal file
View file

@ -0,0 +1,47 @@
# NAME
git-annex assistant - automatically sync changes
# SYNOPSIS
git annex assistant
# DESCRIPTION
Watches for changes to files in the current directory and its subdirectories,
and automatically syncs them to other remotes.
For more details about the git-annex assistant, see
<https://git-annex.branchable.com/assistant/>
# OPTIONS
* `--autostart`
Automatically starts the assistant running in each repository listed
in the file `~/.config/git-annex/autostart`
This is typically started at boot, or when you log in.
* `--startdelay=N`
Wait N seconds before running the startup scan. This process can
be expensive and you may not want to run it immediatly upon login.
* `--foreground`
Avoid forking to the background.
* `--stop`
Stop a running daemon.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

60
doc/git-annex-copy.mdwn Normal file
View file

@ -0,0 +1,60 @@
# NAME
git-annex copy - copy content of files to/from another repository
# SYNOPSIS
git annex copy `[path ...] [--from=remote|--to=remote]`
# DESCRIPTION
Copies the content of files from or to another remote.
# OPTIONS
* `--from=remote`
Use this option to copy the content of files from the specified
remote to the local repository.
* `--to=remote`
Use this option to copy the content of files from the local repository
to the specified remote.
* `--fast`
Avoid contacting the remote to check if it has every file when copying
--to it.
* `--force`
Force checking the remote for every file when copying --from it.
* `--all`
Rather than specifying a filename or path to copy, this option can be
used to copy all available versions of all files.
* `--unused`
Operate on files found by last run of git-annex unused.
* `--key=keyname`
Use this option to move a specified key.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to copy.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

45
doc/git-annex-drop.mdwn Normal file
View file

@ -0,0 +1,45 @@
# NAME
git-annex drop - indicate content of files not currently wanted
# 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.
# OPTIONS
* `--from=remote`
Rather than dropping the content of files in the local repository,
this option can specifiy a remote from which the files'
contents should be removed.
* `--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.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to drop.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

18
doc/git-annex-edit.mdwn Normal file
View file

@ -0,0 +1,18 @@
# NAME
git-annex unlock - unlock files for modification
# SYNOPSIS
git annex edit `[path ...]`
# DESCRIPTION
This is an alias for the `unlock` command; see [[git-annex-unlock]](1)
for details.
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

46
doc/git-annex-get.mdwn Normal file
View file

@ -0,0 +1,46 @@
# NAME
git-annex get - make content of annexed files available
# SYNOPSIS
git annex get `[path ...]`
# DESCRIPTION
Makes the content of annexed files available in this repository. This
will involve copying them from a remote repository, or downloading them,
or transferring them from some kind of key-value store.
# OPTIONS
* `--from=remote`
Normally git-annex will choose which remotes to get the content
from. Use this option to specify which remote to use.
* `--all`
Rather than specifying a filename or path to get, this option can be
used to get all available versions of all files.
* `--key=keyname`
Use this option to get a specified key.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to get.
# SEE ALSO
[[git-annex]](1)
[[git-annex-drop]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

69
doc/git-annex-import.mdwn Normal file
View file

@ -0,0 +1,69 @@
# NAME
git-annex import - move and add files from outside git working copy
# SYNOPSIS
git annex import `[path ...]`
# DESCRIPTION
Moves files from somewhere outside the git working copy, and adds them to
the annex. Individual files to import can be specified.
If a directory is specified, the entire directory is imported.
git annex import /media/camera/DCIM/*
By default, importing two files with the same contents from two different
locations will result in both files being added to the repository.
(With all checksumming backends, including the default SHA256E,
only one copy of the data will be stored.)
# OPTIONS
* `--duplicate`
Do not delete files from the import location.
This could allow importing the same files repeatedly
to different locations in a repository. More likely, it could be used to
import the same files to a number of different branches or separate git
repositories.
* `--deduplicate`
Only import files whose content has not been seen before by git-annex.
Duplicate files will be deleted from the import location.
* `--skip-duplicates`
Only import files whose content has not been seen before by git-annex,
but avoid deleting duplicate files.
* `--clean-duplicates`
Does not import any files, but any files found in the import location
that are duplicates of content in the annex are deleted.
* file matching options
Many of the [[git-annex-matching-options]](1)
can be used to specify files to import.
git annex import /dir --include='*.png'
# CAVEATS
Note that using `--deduplicate` or `--clean-duplicates` with the WORM
backend does not look at file content, but filename and mtime.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

46
doc/git-annex-importfeed.mdwn Normal file
View file

@ -0,0 +1,46 @@
# NAME
git-annex importfeed - import files from podcast feeds
# SYNOPSIS
git annex importfeed `[url ...]`
# DESCRIPTION
Imports the contents of podcast feeds. Only downloads files whose
urls have not already been added to the repository before, so you can
delete, rename, etc the resulting files and repeated runs won't duplicate
them.
When quvi is installed, links in the feed are tested to see if they
are on a video hosting site, and the video is downloaded. This allows
importing e.g., youtube playlists.
# OPTIONS
* `--force`
Force downoading urls it's seen before.
* `--template`
Controls where the files are stored.
The default template is '${feedtitle}/${itemtitle}${extension}'
Other available variables for templates: feedauthor, itemauthor, itemsummary, itemdescription, itemrights, itemid, itempubdate, title, author
* `--relaxed`, `--fast`, `--raw`, `--template`
These options behave the same as when using [[git-annex-addurl]](1).
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

29
doc/git-annex-lock.mdwn Normal file
View file

@ -0,0 +1,29 @@
# NAME
git-annex lock - unco unlock command
# SYNOPSIS
git annex lock `[path ...]`
# DESCRIPTION
Use this to undo an unlock command if you don't want to modify
the files, or have made modifications you want to discard.
# OPTIONS
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to lock.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

164
doc/git-annex-matching-options.mdwn Normal file
View file

@ -0,0 +1,164 @@
# NAME
git-annex-matching-options - specifying files to act on
# DESCRIPTION
Many git-annex commands support using these options to specify which
files they act on.
Arbitrarily complicated expressions can be built using these options.
For example:
--exclude '*.mp3' --and --not -( --in=usbdrive --or --in=archive -)
The above example prevents git-annex from working on mp3 files whose
file contents are present at either of two repositories.
# OPTIONS
* `--exclude=glob`
Skips files matching the glob pattern. The glob is matched relative to
the current directory. For example:
--exclude='*.mp3' --exclude='subdir/*'
Note that this will not match anything when using --all or --unused.
* `--include=glob`
Skips files not matching the glob pattern. (Same as `--not --exclude`.)
For example, to include only mp3 and ogg files:
--include='*.mp3' --or --include='*.ogg'
Note that this will not skip anything when using --all or --unused.
* `--in=repository`
Matches only files that git-annex believes have their contents present
in a repository. Note that it does not check the repository to verify
that it still has the content.
The repository should be specified using the name of a configured remote,
or the UUID or description of a repository. For the current repository,
use `--in=here`
* `--in=repository@{date}`
Matches files currently in the work tree whose content was present in
the repository on the given date.
The date is specified in the same syntax documented in
gitrevisions(7). Note that this uses the reflog, so dates far in the
past cannot be queried.
For example, you might need to run `git annex drop .` to temporarily
free up disk space. The next day, you can get back the files you dropped
using `git annex get . --in=here@{yesterday}`
* `--copies=number`
Matches only files that git-annex believes to have the specified number
of copies, or more. Note that it does not check remotes to verify that
the copies still exist.
* `--copies=trustlevel:number`
Matches only files that git-annex believes have the specified number of
copies, on remotes with the specified trust level. For example,
`--copies=trusted:2`
To match any trust level at or higher than a given level,
use 'trustlevel+'. For example, `--copies=semitrusted+:2`
* `--copies=groupname:number`
Matches only files that git-annex believes have the specified number of
copies, on remotes in the specified group. For example,
`--copies=archive:2`
* `--lackingcopies=number`
Matches only files that git-annex believes need the specified number or
more additional copies to be made in order to satisfy their numcopies
settings.
* `--approxlackingcopies=number`
Like lackingcopies, but does not look at .gitattributes annex.numcopies
settings. This makes it significantly faster.
* `--inbackend=name`
Matches only files whose content is stored using the specified key-value
backend.
* `--inallgroup=groupname`
Matches only files that git-annex believes are present in all repositories
in the specified group.
* `--smallerthan=size`
* `--largerthan=size`
Matches only files whose content is smaller than, or larger than the
specified size.
The size can be specified with any commonly used units, for example,
"0.5 gb" or "100 KiloBytes"
* `--metadata field=glob`
Matches only files that have a metadata field attached with a value that
matches the glob. The values of metadata fields are matched case
insensitively.
* `--want-get`
Matches files that the preferred content settings for the repository
make it want to get. Note that this will match even files that are
already present, unless limited with e.g., `--not --in .`
Note that this will not match anything when using --all or --unused.
* `--want-drop`
Matches files that the preferred content settings for the repository
make it want to drop. Note that this will match even files that have
already been dropped, unless limited with e.g., `--in .`
Note that this will not match anything when using --all or --unused.
* `--not`
Inverts the next matching option. For example, to only act on
files with less than 3 copies, use `--not --copies=3`
* `--and`
Requires that both the previous and the next matching option matches.
The default.
* `--or`
Requires that either the previous, or the next matching option matches.
* `-(`
Opens a group of matching options.
* `-)`
Closes a group of matching options.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

27
doc/git-annex-merge.mdwn Normal file
View file

@ -0,0 +1,27 @@
# NAME
git-annex merge - automatically merge changes from remotes
# SYNOPSIS
git annex merge
# DESCRIPTION
This performs the same merging (and merge conflict resolution)
that is done by the sync command, but without pushing or pulling any
data.
One way to use this is to put `git annex merge` into a repository's
post-receive hook. Then any syncs to the repository will update its
working copy automatically.
# 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-mirror.mdwn Normal file
View file

@ -0,0 +1,55 @@
# NAME
git-annex mirror - mirror content of files to/from another repository
# SYNOPSIS
git annex mirror `[path ...] [--to=remote|--from=remote]`
# DESCRIPTION
This causes a destination repository to mirror a source repository.
Each specified file in the source repository is mirrored to the destination
repository. If a file's content is present in the source repository, it is
copied to the destination repository. If a file's content is not present in
the source repository, it will be dropped from the destination repository
when the numcopies setting allows.
Note that mirror does not sync the git repository, but only the file
contents.
# OPTIONS
* `--to=remote`
Use the local repository as the source repository, and mirror its contents
to the remote.
* `--from=remote`
Use the remote as the source repository, and mirror its contents to the local
repository.
* `--all`
Mirror 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.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to mirror.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

51
doc/git-annex-move.mdwn Normal file
View file

@ -0,0 +1,51 @@
# NAME
git-annex move - move content of files to/from another repository
# SYNOPSIS
git annex move `[path ...] [--from=remote|--to=remote]`
# DESCRIPTION
Moves the content of files from or to another remote.
# OPTIONS
* `--from=remote`
Use this option to move the content of files from the specified
remote to the local repository.
* `--to=remote`
Use this option to move the content of files from the local repository
to the specified remote.
* `--all`
Rather than specifying a filename or path to move, this option can be
used to move all available versions of all files.
* `--unused`
Operate on files found by last run of git-annex unused.
* `--key=keyname`
Use this option to move a specified key.
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to move.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

45
doc/git-annex-preferred-content.mdwn Normal file
View file

@ -0,0 +1,45 @@
# NAME
git-annex-preferred-content -
# DESCRIPTION
Each repository has a preferred content setting, which specifies content
that the repository wants to have present. These settings can be configured
using `git annex vicfg` or `git annex wanted`.
They are used by the `--auto` option, by `git annex sync --content`,
and by the git-annex assistant.
Preferred content expressions are similar, but not identical to
the [[git-annex-matching-options]](1), just without the dashes.
For example:
exclude=archive/* and (include=*.mp3 or smallerthan=1mb)
The main differences are that `exclude=` and `include=` always
match relative to the top of the git repository, and that there is
no equivilant to `--in`.
For more details about preferred content expressions, see
See <https://git-annex.branchable.com/preferred_content/>
When a repository is in one of the standard predefined groups, like "backup"
and "client", setting its preferred content to "standard" will use a
built-in preferred content expression developed for that group.
See <https://git-annex.branchable.com/preferred_content/standard_groups/>
If you have set a groupwanted expression for a group, it will be used
when a repository in the group has its preferred content set to
"groupwanted".
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
<http://git-annex.branchable.com/>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

21
doc/git-annex-rmurl.mdwn Normal file
View file

@ -0,0 +1,21 @@
# NAME
git-annex rmurl - record file is not available at url
# SYNOPSIS
git annex rmurl `file url`
# DESCRIPTION
Record that the file is no longer available at the url.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

47
doc/git-annex-schedule.mdwn Normal file
View file

@ -0,0 +1,47 @@
# NAME
git-annex schedule - get or set scheduled jobs
# SYNOPSIS
git annex schedule `repository [expression]`
# DESCRIPTION
The [[git-annex-assistant]](1) daemon can be configured to run scheduled jobs.
This is similar to cron and anacron (and you can use them if you prefer),
but has the advantage of being integrated into git-annex, and so being able
to e.g., fsck a repository on a removable drive when the drive gets
connected.
When run with an expression, configures scheduled jobs to run at a
particular time. This can be used to make the assistant periodically run
incremental fscks.
When run without an expression, outputs the current scheduled jobs for
the repository.
# EXPRESSIONS
These actions are available: "fsck self", "fsck UUID" (where UUID
is the UUID of a remote to fsck). After the action comes the duration
to allow the action to run, and finally the schedule of when to run it.
To schedule multiple jobs, separate them with "; ".
Some examples:
fsck self 30m every day at any time
fsck self 1h every month at 3 AM
fsck self 1h on day 1 of every month at any time
fsck self 1h every week divisible by 2 at any time
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

31
doc/git-annex-status.mdwn Normal file
View file

@ -0,0 +1,31 @@
# NAME
git-annex status - show the working tree status
# SYNOPSIS
git annex status `[path ...]`
# DESCRIPTION
Similar to `git status --short`, this command displays the status of the files
in the working tree. Shows files that are not checked into git, files that have
been deleted, and files that have been modified.
Particularly useful in direct mode.
# OPTIONS
* `--json`
Enable JSON output.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

64
doc/git-annex-sync.mdwn Normal file
View file

@ -0,0 +1,64 @@
# NAME
git-annex sync - synchronize local repository with remotes
# SYNOPSIS
git annex sync `[remote ...]`
# DESCRIPTION
Use this command when you want to synchronize the local repository with
one or more of its remotes. You can specify the remotes (or remote
groups) to sync with by name; the default if none are specified is to
sync with all remotes.
The sync process involves first committing any local changes to files
that have previously been added to the repository,
then fetching and merging the `synced/master` and the `git-annex` branch
from the remote repositories, and finally pushing the changes back to
those branches on the remote repositories. You can use standard git
commands to do each of those steps by hand, or if you don't want to
worry about the details, you can use sync.
Merge conflicts are automatically handled by sync. When two conflicting
versions of a file have been committed, both will be added to the tree,
under different filenames. For example, file "foo" would be replaced
with "foo.somekey" and "foo.otherkey".
Note that syncing with a remote will not update the remote's working
tree with changes made to the local repository. However, those changes
are pushed to the remote, so they can be merged into its working tree
by running "git annex sync" on the remote.
# OPTIONS
* `--fast`
Only sync with the remotes with the lowest annex-cost value configured.
* `--content`
Normally, syncing does not transfer the contents of annexed files.
This option causes the file contents to also be uploaded and downloaded
as necessary.
By default, this tries to get each annexed file that the local repository
does not yet have, and then copies each file to every remote that it is
syncing with. This behavior can be overridden by configuring the preferred
content of a repository. See [git-annex-preferred-content](1)
* `--message=msg`
Use this option to specify a commit message.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

33
doc/git-annex-undo.mdwn Normal file
View file

@ -0,0 +1,33 @@
# NAME
git-annex undo - undo last change to a file or directory
# SYNOPSIS
git annex `[filename|directory] ...`
# DESCRIPTION
When passed a filename, undoes the last change that was made to that
file.
When passed a directory, undoes the last change that was made to the
contents of that directory.
Running undo a second time will undo the undo, returning the working
tree to the same state it had before. In order for undoing an undo of
staged changes, any staged changes are first committed by the
undo command.
Note that this does not undo get/drop of a file's content; it only
operates on the file tree committed to git.
# 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-unlock.mdwn Normal file
View file

@ -0,0 +1,32 @@
# NAME
git-annex unlock - unlock files for modification
# SYNOPSIS
git annex unlock `[path ...]`
# DESCRIPTION
Normally, the content of annexed files is protected from being changed.
Unlocking an annexed file allows it to be modified. This replaces the
symlink for each specified file with a copy of the file's content.
You can then modify it and `git annex add` (or `git commit`) to inject
it back into the annex.
# OPTIONS
* file matching options
The [[git-annex-matching-options]](1)
can be used to specify files to unlock.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

43
doc/git-annex-watch.mdwn Normal file
View file

@ -0,0 +1,43 @@
# NAME
git-annex watch - watch for changes
# SYNOPSIS
git annex watch
# DESCRIPTION
Watches for changes to files in the current directory and its subdirectories,
and takes care of automatically adding new files, as well as dealing with
deleted, copied, and moved files. With this running as a daemon in the
background, you no longer need to manually run git commands when
manipulating your files.
By default, all files in the directory will be added to the repository.
(Including dotfiles.) To block some files from being added, use
`.gitignore` files.
By default, all files that are added are added to the annex, the same
as when you run `git annex add`. If you configure annex.largefiles,
files that it does not match will instead be added with `git add`.
# OPTIONS
* `--foreground`
Avoid forking to the background.
* `--stop`
Stop a running daemon.
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

49
doc/git-annex-webapp.mdwn Normal file
View file

@ -0,0 +1,49 @@
# NAME
git-annex webapp - launch webapp
# SYNOPSIS
git annex webapp
# DESCRIPTION
Opens a web app, that allows easy setup of a git-annex repository,
and control of the git-annex assistant. If the assistant is not
already running, it will be started.
By default, the webapp can only be accessed from localhost, and running
it opens a browser window.
# OPTIONS
* `--listen=address`
Useful for using the webapp on a remote computer. This makes the webapp
listen on the specified address.
This disables running a local web browser, and outputs the url you
can use to open the webapp.
Set annex.listen in the git config to make the webapp always
listen on an address.
# USING HTTPS
When using the webapp on a remote computer, you'll almost certainly
want to enable HTTPS. The webapp will use HTTPS if it finds
a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's
one way to generate those files, using a self-signed certificate:
openssl genrsa -out .git/annex/privkey.pem 4096
openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem
# SEE ALSO
[[git-annex]](1)
# AUTHOR
Joey Hess <id@joeyh.name>
Warning: Automatically converted into a man page by mdwn2man. Edit with care.

484
doc/git-annex.mdwn
View file

@ -65,70 +65,44 @@ subdirectories).
Adds files in the path to the annex. If no path is specified, adds
files from the current directory and below.
Files that are already checked into git, or that git has been configured
to ignore will be silently skipped. (Use `--force` to add ignored files.)
Dotfiles are skipped unless explicitly listed, or the --include-dotfiles
option is used.
See [[git-annex-add]](1) for details.
* `get [path ...]`
Makes the content of annexed files available in this repository. This
will involve copying them from another repository, or downloading them,
or transferring them from some kind of key-value store.
Makes the content of annexed files available in this repository.
Normally git-annex will choose which repository to copy the content from,
but you can override this using the `--from` option.
Rather than specifying a filename, the `--all` option can be used to
get all available versions of all files, or the --key=KEY`
option can be used to get a specified key.
See [[git-annex-get]](1) for details.
* `drop [path ...]`
Drops the content of annexed files from this repository.
git-annex will refuse to drop content if it cannot verify it is
safe to do so. This can be overridden with the `--force` switch.
See [[git-annex-drop]](1) for details.
To drop content from a remote, specify `--from`.
* `move [path ...] [--from=remote|--to=remote]`
* `move [path ...]`
Moves the content of files from or to another remote.
When used with the `--from` option, moves the content of annexed files
from the specified repository to the current one.
See [[git-annex-move]](1) for details.
When used with the `--to` option, moves the content of annexed files from
the current repository to the specified one.
* `copy [path ...] [--from=remote|--to=remote]`
* `copy [path ...]`
Copies the content of files from or to another remote.
When used with the `--from` option, copies the content of annexed files
from the specified repository to the current one.
When used with the `--to` option, copies the content of annexed files from
the current repository to the specified one.
To avoid contacting the remote to check if it has every file
when copying --to the repository, specify `--fast`
To force checking the remote for every file when copying --from the
repository, specify `--force`.
See [[git-annex-copy]](1) for details.
* `status [path ...]`
Similar to `git status --short`, displays the status of the files in the
working tree. Shows files that are not checked into git, files that
have been deleted, and files that have been modified.
Particularly useful in direct mode.
working tree. Particularly useful in direct mode.
See [[git-annex-status]](1) for details.
* `unlock [path ...]`
Normally, the content of annexed files is protected from being changed.
Unlocking an annexed file allows it to be modified. This replaces the
symlink for each specified file with a copy of the file's content.
You can then modify it and `git annex add` (or `git commit`) to inject
it back into the annex.
Unlock annexed files for modification.
See [[git-annex-unlock]](1) for details.
* `edit [path ...]`
@ -140,208 +114,61 @@ subdirectories).
Use this to undo an unlock command if you don't want to modify
the files, or have made modifications you want to discard.
See [[git-annex-lock]](1) for details.
* `sync [remote ...]`
Use this command when you want to synchronize the local repository with
one or more of its remotes. You can specify the remotes (or remote
groups) to sync with by name; the default if none are specified is to
sync with all remotes.
Or specify `--fast` to sync with the remotes with the
lowest annex-cost value.
Synchronize local repository with remotes.
The sync process involves first committing any local changes to files
that have previously been added to the repository,
then fetching and merging the `synced/master` and the `git-annex` branch
from the remote repositories, and finally pushing the changes back to
those branches on the remote repositories. You can use standard git
commands to do each of those steps by hand, or if you don't want to
worry about the details, you can use sync.
See [[git-annex-sync]](1) for details.
Merge conflicts are automatically handled by sync. When two conflicting
versions of a file have been committed, both will be added to the tree,
under different filenames. For example, file "foo" would be replaced
with "foo.somekey" and "foo.otherkey".
* `mirror [path ...] [--to=remote|--from=remote]`
Note that syncing with a remote will not update the remote's working
tree with changes made to the local repository. However, those changes
are pushed to the remote, so they can be merged into its working tree
by running "git annex sync" on the remote.
Mirror content of files to/from another repository.
With the `--content` option, the contents of annexed files in the work
tree will also be uploaded and downloaded from remotes. By default,
this tries to get each annexed file that the local repository does not
yet have, and then copies each file to every remote that it is syncing with.
This behavior can be overridden by configuring the preferred content of
a repository. See see PREFERRED CONTENT below.
The `--message` or `-m` option can be used to specify a commit message.
* `merge`
This performs the same merging (and merge conflict resolution)
that is done by the sync command, but without pushing or pulling any data.
One way to use this is to put `git annex merge` into a repository's
post-receive hook. Then any syncs to the repository will update its working
copy automatically.
* `mirror [path ...]`
This causes a destination repository to mirror a source repository.
To use the local repository as the source repository,
specify mirror `--to` remote.
To use a remote as the source repository, specify mirror `--from` remote.
Each specified file in the source repository is mirrored to the destination
repository. If a file's content is present in the source repository, it is
copied to the destination repository. If a file's content is not present in
the source repository, it will be dropped from the destination repository
when the numcopies setting allows.
Note that mirror does not sync the git repository, but only the file
contents.
Also, --all may be specified to mirror 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.
See [[git-annex-mirror]](1) for details.
* `addurl [url ...]`
Downloads each url to its own file, which is added to the annex.
To avoid immediately downloading the url, specify `--fast`.
To avoid storing the size of the url's content, and accept whatever
is there at a future point, specify `--relaxed`. (Implies `--fast`.)
Normally the filename is based on the full url, so will look like
"www.example.com_dir_subdir_bigfile". In some cases, addurl is able to
come up with a better filename based on other information. Or, for a
shorter filename, specify `--pathdepth=N`. For example,
`--pathdepth=1` will use "dir/subdir/bigfile",
while `--pathdepth=3` will use "bigfile". It can also be negative;
`--pathdepth=-2` will use the last two parts of the url.
Or, to directly specify what file the url is added to, specify `--file`.
This changes the behavior; now all the specified urls are recorded as
alternate locations from which the file can be downloaded. In this mode,
addurl can be used both to add new files, or to add urls to existing files.
When `quvi` is installed, urls are automatically tested to see if they
point to a video hosting site, and the video is downloaded instead.
Urls to torrent files (including magnet links) will cause the content of
the torrent to be downloaded, using `aria2c`.
To prevent special handling of urls by quvi, bittorrent, and other
special remotes, specify `--raw`. This will for example, make addurl
download the .torrent file and not the contents it points to.
See [[git-annex-addurl]](1) for details.
* `rmurl file url`
Record that the file is no longer available at the url.
See [[git-annex-rmurl]](1) for details.
* `import [path ...]`
Moves files from somewhere outside the git working copy, and adds them to
the annex. Individual files to import can be specified.
If a directory is specified, the entire directory is imported.
Move and add files from outside git working copy into the annex.
git annex import /media/camera/DCIM/*
By default, importing two files with the same contents from two different
locations will result in both files being added to the repository.
(With all checksumming backends, including the default SHA256E,
only one copy of the data will be stored.)
To not delete files from the import location, use the
`--duplicate` option. This could allow importing the same files repeatedly
to different locations in a repository. More likely, it could be used to
import the same files to a number of different branches or separate git
repositories.
To only import files whose content has not been seen before by git-annex,
use the `--deduplicate` option. Duplicate files will be deleted from the
import location.
To only import files whose content has not been seen before by git-annex,
but avoid deleting duplicate files, use the `--skip-duplicates` option.
The `--clean-duplicates` option does not import any new files, but any files
found in the import location that are duplicates of content in the annex
are deleted.
(Note that using `--deduplicate` or `--clean-duplicates` with the WORM
backend does not look at file content, but filename and mtime.)
To control which files are imported, many of the MATCHING OPTIONS can
be used.
git annex import /dir --include='*.png'
See [[git-annex-import]](1) for details.
* `importfeed [url ...]`
Imports the contents of podcast feeds. Only downloads files whose
urls have not already been added to the repository before, so you can
delete, rename, etc the resulting files and repeated runs won't duplicate
them. (Use `--force` to force downloading urls it's seen before.)
Imports the contents of podcast feeds into the annex.
Use `--template` to control where the files are stored.
The default template is '${feedtitle}/${itemtitle}${extension}'
(Other available variables: feedauthor, itemauthor, itemsummary, itemdescription, itemrights, itemid, itempubdate, title, author)
The `--relaxed`, `--fast`, and `--raw` options behave the same as they
do in addurl.
When quvi is installed, links in the feed are tested to see if they
are on a video hosting site, and the video is downloaded. This allows
importing e.g., youtube playlists.
See [[git-annex-importfeed]](1) for details.
* `undo [filename|directory] ...`
When passed a filename, undoes the last change that was made to that
file.
Undo last change to a file or directory.
When passed a directory, undoes the last change that was made to the
contents of that directory.
Running undo a second time will undo the undo, returning the working
tree to the same state it had before. In order for undoing an undo of
staged changes, any staged changes are first committed by the
undo command.
Note that this does not undo get/drop of a file's content; it only
operates on the file tree committed to git.
See [[git-annex-undo]](1) for details.
* `watch`
Watches for changes to files in the current directory and its subdirectories,
and takes care of automatically adding new files, as well as dealing with
deleted, copied, and moved files. With this running as a daemon in the
background, you no longer need to manually run git commands when
manipulating your files.
Watch for changes and autocommit.
By default, all files in the directory will be added to the repository.
(Including dotfiles.) To block some files from being added, use
`.gitignore` files.
By default, all files that are added are added to the annex, the same
as when you run `git annex add`. If you configure annex.largefiles,
files that it does not match will instead be added with `git add`.
To not daemonize, run with `--foreground` ; to stop a running daemon,
run with `--stop`.
See [[git-annex-watch]](1) for details.
* `assistant`
Like watch, but also automatically syncs changes to other remotes.
Typically started at boot, or when you log in.
Atomatically sync folders between devices.
With the `--autostart` option, the assistant is started in any repositories
it has created. These are listed in `~/.config/git-annex/autostart`.
See [[git-annex-assistant]](1) for details.
* `webapp`
@ -349,22 +176,7 @@ subdirectories).
and control of the git-annex assistant. If the assistant is not
already running, it will be started.
By default, the webapp can only be accessed from localhost, and running
it opens a browser window.
To use the webapp on a remote computer, use the `--listen=address`
option to specify the address the web server should listen on
(or set annex.listen).
This disables running a local web browser, and outputs the url you
can use to open the webapp.
When using the webapp on a remote computer, you'll almost certainly
want to enable HTTPS. The webapp will use HTTPS if it finds
a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's
one way to generate those files, using a self-signed certificate:
openssl genrsa -out .git/annex/privkey.pem 4096
openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem
See [[git-annex-webapp]](1) for details.
# REPOSITORY SETUP COMMANDS
@ -531,9 +343,9 @@ subdirectories).
* `schedule repository [expression]`
When run with an expression, configures scheduled jobs to run at a
particular time. This can be used to make the assistant periodically run
incremental fscks. See SCHEDULED JOBS below.
Get or set scheduled jobs.
See [[git-annex-schedule]](1) for details.
* `vicfg`
@ -630,6 +442,12 @@ subdirectories).
This is useful to run if you have been moving the symlinks around,
but is done automatically when committing a change with git too.
* `merge`
Automatically merge changes from remotes.
See [[git-annex-merge]](1) for details.
* `upgrade`
Upgrades the repository to current layout.
@ -690,8 +508,8 @@ subdirectories).
finds files in the current directory and its subdirectories.
By default, only lists annexed files whose content is currently present.
This can be changed by specifying matching options. To list all
annexed files, present or not, specify `--include "*"`. To list all
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,
@ -734,8 +552,9 @@ subdirectories).
When no item is specified, displays statistics and information
for the repository as a whole.
When a directory is specified, the MATCHING OPTIONS can be used
to select the files in the directory that are included in the statistics.
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.
To only show the data that can be gathered quickly, use `--fast`.
@ -1265,205 +1084,6 @@ subdirectories).
Overrides git configuration settings. May be specified multiple times.
# MATCHING OPTIONS
These options can all be specified multiple times, and can be combined to
limit which files git-annex acts on.
Arbitrarily complicated expressions can be built using these options.
For example:
--exclude '*.mp3' --and --not -( --in=usbdrive --or --in=archive -)
The above example prevents git-annex from working on mp3 files whose
file contents are present at either of two repositories.
* `--exclude=glob`
Skips files matching the glob pattern. The glob is matched relative to
the current directory. For example:
--exclude='*.mp3' --exclude='subdir/*'
Note that this will not match anything when using --all or --unused.
* `--include=glob`
Skips files not matching the glob pattern. (Same as `--not --exclude`.)
For example, to include only mp3 and ogg files:
--include='*.mp3' --or --include='*.ogg'
Note that this will not skip anything when using --all or --unused.
* `--in=repository`
Matches only files that git-annex believes have their contents present
in a repository. Note that it does not check the repository to verify
that it still has the content.
The repository should be specified using the name of a configured remote,
or the UUID or description of a repository. For the current repository,
use `--in=here`
* `--in=repository@{date}`
Matches files currently in the work tree whose content was present in
the repository on the given date.
The date is specified in the same syntax documented in
gitrevisions(7). Note that this uses the reflog, so dates far in the
past cannot be queried.
For example, you might need to run `git annex drop .` to temporarily
free up disk space. The next day, you can get back the files you dropped
using `git annex get . --in=here@{yesterday}`
* `--copies=number`
Matches only files that git-annex believes to have the specified number
of copies, or more. Note that it does not check remotes to verify that
the copies still exist.
* `--copies=trustlevel:number`
Matches only files that git-annex believes have the specified number of
copies, on remotes with the specified trust level. For example,
`--copies=trusted:2`
To match any trust level at or higher than a given level,
use 'trustlevel+'. For example, `--copies=semitrusted+:2`
* `--copies=groupname:number`
Matches only files that git-annex believes have the specified number of
copies, on remotes in the specified group. For example,
`--copies=archive:2`
* `--lackingcopies=number`
Matches only files that git-annex believes need the specified number or
more additional copies to be made in order to satisfy their numcopies
settings.
* `--approxlackingcopies=number`
Like lackingcopies, but does not look at .gitattributes annex.numcopies
settings. This makes it significantly faster.
* `--inbackend=name`
Matches only files whose content is stored using the specified key-value
backend.
* `--inallgroup=groupname`
Matches only files that git-annex believes are present in all repositories
in the specified group.
* `--smallerthan=size`
* `--largerthan=size`
Matches only files whose content is smaller than, or larger than the
specified size.
The size can be specified with any commonly used units, for example,
"0.5 gb" or "100 KiloBytes"
* `--metadata field=glob`
Matches only files that have a metadata field attached with a value that
matches the glob. The values of metadata fields are matched case
insensitively.
* `--want-get`
Matches files that the preferred content settings for the repository
make it want to get. Note that this will match even files that are
already present, unless limited with e.g., `--not --in .`
Note that this will not match anything when using --all or --unused.
* `--want-drop`
Matches files that the preferred content settings for the repository
make it want to drop. Note that this will match even files that have
already been dropped, unless limited with e.g., `--in .`
Note that this will not match anything when using --all or --unused.
* `--not`
Inverts the next matching option. For example, to only act on
files with less than 3 copies, use `--not --copies=3`
* `--and`
Requires that both the previous and the next matching option matches.
The default.
* `--or`
Requires that either the previous, or the next matching option matches.
* `-(`
Opens a group of matching options.
* `-)`
Closes a group of matching options.
# PREFERRED CONTENT
Each repository has a preferred content setting, which specifies content
that the repository wants to have present. These settings can be configured
using `git annex vicfg` or `git annex wanted`.
They are used by the `--auto` option, and by the git-annex assistant.
The preferred content settings are similar, but not identical to
the matching options specified above, just without the dashes.
For example:
exclude=archive/* and (include=*.mp3 or smallerthan=1mb)
The main differences are that `exclude=` and `include=` always
match relative to the top of the git repository, and that there is
no equivilant to `--in`.
When a repository is in one of the standard predefined groups, like "backup"
and "client", setting its preferred content to "standard" will use a
built-in preferred content expression developed for that group.
See <https://git-annex.branchable.com/preferred_content/standard_groups/>
If you have set a groupwanted expression for a group, it will be used
when a repository in the group has its preferred content set to
"groupwanted".
# SCHEDULED JOBS
The git-annex assistant daemon can be configured to run scheduled jobs.
This is similar to cron and anacron (and you can use them if you prefer),
but has the advantage of being integrated into git-annex, and so being able
to e.g., fsck a repository on a removable drive when the drive gets
connected.
The scheduled jobs can be configured using `git annex vicfg` or
`git annex schedule`.
These actions are available: "fsck self", "fsck UUID" (where UUID
is the UUID of a remote to fsck). After the action comes the duration
to allow the action to run, and finally the schedule of when to run it.
To schedule multiple jobs, separate them with "; ".
Some examples:
fsck self 30m every day at any time
fsck self 1h every month at 3 AM
fsck self 1h on day 1 of every month at any time
fsck self 1h every week divisible by 2 at any time
# CONFIGURATION VIA .git/config
Like other git commands, git-annex is configured via `.git/config`.
@ -1963,7 +1583,7 @@ whenever the git-annex branch is updated. You can make this hook run
# SEE ALSO
Most of git-annex's documentation is available on its web site,
More git-annex documentation is available on its web site,
<http://git-annex.branchable.com/>
If git-annex is installed from a package, a copy of its documentation

2
doc/internals.mdwn
View file

@ -241,7 +241,7 @@ space and then its schedule, followed by a timestamp.
There can be multiple events in the schedule, separated by "; ".
The format of the scheduled events is the same described in
the SCHEDULED JOBS section of the man page.
[[git-annex-schedule]].
Example: