489 lines
16 KiB
Markdown
489 lines
16 KiB
Markdown
# NAME
|
|
|
|
git-annex - manage files with git, without checking their contents in
|
|
|
|
# SYNOPSIS
|
|
|
|
git annex command [params ...]
|
|
|
|
# DESCRIPTION
|
|
|
|
git-annex allows managing files with git, without checking the file
|
|
contents into git. While that may seem paradoxical, it is useful when
|
|
dealing with files larger than git can currently easily handle, whether due
|
|
to limitations in memory, checksumming time, or disk space.
|
|
|
|
Even without file content tracking, being able to manage files with git,
|
|
move files around and delete files with versioned directory trees, and use
|
|
branches and distributed clones, are all very handy reasons to use git. And
|
|
annexed files can co-exist in the same git repository with regularly
|
|
versioned files, which is convenient for maintaining documents, Makefiles,
|
|
etc that are associated with annexed files but that benefit from full
|
|
revision control.
|
|
|
|
When a file is annexed, its content is moved into a key-value store, and
|
|
a symlink is made that points to the content. These symlinks are checked into
|
|
git and versioned like regular files. You can move them around, delete
|
|
them, and so on. Pushing to another git repository will make git-annex
|
|
there aware of the annexed file, and it can be used to retrieve its
|
|
content from the key-value store.
|
|
|
|
# EXAMPLES
|
|
|
|
# git annex get video/hackity_hack_and_kaxxt.mov
|
|
get video/_why_hackity_hack_and_kaxxt.mov (not available)
|
|
I was unable to access these remotes: server
|
|
Try making some of these repositories available:
|
|
5863d8c0-d9a9-11df-adb2-af51e6559a49 -- my home file server
|
|
58d84e8a-d9ae-11df-a1aa-ab9aa8c00826 -- portable USB drive
|
|
ca20064c-dbb5-11df-b2fe-002170d25c55 -- backup SATA drive
|
|
failed
|
|
# sudo mount /media/usb
|
|
# git remote add usbdrive /media/usb
|
|
# git annex get video/hackity_hack_and_kaxxt.mov
|
|
get video/hackity_hack_and_kaxxt.mov (copying from usbdrive...) ok
|
|
# git commit -a -m "got a video I want to rewatch on the plane"
|
|
|
|
# git annex add iso
|
|
add iso/Debian_5.0.iso ok
|
|
# git commit -a -m "saving Debian CD for later"
|
|
|
|
# git annex drop iso/Debian_4.0.iso
|
|
drop iso/Debian_4.0.iso ok
|
|
# git commit -a -m "freed up space"
|
|
|
|
# git annex move iso --to=usbdrive
|
|
move iso/Debian_5.0.iso (moving to usbdrive...) ok
|
|
|
|
# COMMANDS
|
|
|
|
Like many git commands, git-annex can be passed a path that
|
|
is either a file or a directory. In the latter case it acts on all relevant
|
|
files in the directory. If no path is specified, most git-annex commands
|
|
default to acting on all relevant files in the current directory (and
|
|
subdirectories).
|
|
|
|
Many git-annex commands will stage changes for later `git commit` by you.
|
|
|
|
* add [path ...]
|
|
|
|
Adds files in the path to the annex. Files that are already checked into
|
|
git, or that git has been configured to ignore will be silently skipped.
|
|
|
|
* get [path ...]
|
|
|
|
Makes the content of annexed files available in this repository. Depending
|
|
on the backend used, this will involve copying them from another repository,
|
|
or downloading them, or transferring them from some kind of key-value store.
|
|
|
|
* drop [path ...]
|
|
|
|
Drops the content of annexed files from this repository.
|
|
|
|
git-annex may refuse to drop content if the backend does not think
|
|
it is safe to do so, typically because of the setting of annex.numcopies.
|
|
|
|
* move [path ...]
|
|
|
|
When used with the --from option, moves the content of annexed files
|
|
from the specified repository to the current one.
|
|
|
|
When used with the --to option, moves the content of annexed files from
|
|
the current repository to the specified one.
|
|
|
|
* copy [path ...]
|
|
|
|
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, specify --fast
|
|
|
|
* unlock [path ...]
|
|
|
|
Normally, the content of annexed files is protected from being changed.
|
|
Unlocking a 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.
|
|
|
|
* edit [path ...]
|
|
|
|
This is an alias for the unlock command. May be easier to remember,
|
|
if you think of this as allowing you to edit an annexed file.
|
|
|
|
* lock [path ...]
|
|
|
|
Use this to undo an unlock command if you don't want to modify
|
|
the files, or have made modifications you want to discard.
|
|
|
|
* init description
|
|
|
|
Initializes git-annex with a description of the git repository,
|
|
and sets up `.gitattributes` and the pre-commit hook.
|
|
|
|
* describe repository description
|
|
|
|
Changes the description of a git repository.
|
|
|
|
The repository to describe can be specified by git remote name or
|
|
by uuid. To change the description of the current repository, use
|
|
"."
|
|
|
|
* s3bucket name description [datacenter host port] [--key=gpgkey]
|
|
|
|
Creates a bucket in Amazon S3. The bucket's name can be used
|
|
to configure git remote using the bucket.
|
|
|
|
The datacenter defaults to "US". Other values include "EU",
|
|
"us-west-1", and "ap-southeast-1".
|
|
|
|
To use a different, S3-compatable service, specify a host and port.
|
|
|
|
By default, data (including filenames) is encrypted using gpg.
|
|
To use a key other than the default gpg key, specify it with
|
|
the --key option. To disable encryption, specify "none".
|
|
|
|
* fsck [path ...]
|
|
|
|
With no parameters, this command checks the whole annex for consistency,
|
|
and warns about or fixes any problems found.
|
|
|
|
With parameters, only the specified files are checked.
|
|
|
|
To avoid expensive checksum calculations, specify --fast
|
|
|
|
* unused
|
|
|
|
Checks the annex for data that is not used by any files currently
|
|
in the annex, and prints a numbered list of the data.
|
|
|
|
To only show unused temp files, specify --fast
|
|
|
|
* dropunused [number ...]
|
|
|
|
Drops the data corresponding to the numbers, as listed by the last
|
|
`git annex unused`
|
|
|
|
* find [path ...]
|
|
|
|
Outputs a list of annexed files whose content is currently present.
|
|
|
|
With no parameters, defaults to finding all files in the current directory
|
|
and its subdirectories.
|
|
|
|
* whereis [path ...]
|
|
|
|
Displays a list of repositories known to contain the content of the
|
|
specified file or files.
|
|
|
|
* migrate [path ...]
|
|
|
|
Changes the specified annexed files to store their content in the
|
|
default backend (or the one specified with --backend). Only files whose
|
|
content is currently available are migrated.
|
|
|
|
Note that the content is not removed from the backend it was previously in.
|
|
Use `git annex unused` to find and remove such content.
|
|
|
|
Normally, nothing will be done to files already in the backend.
|
|
However, if a backend changes the information it uses to construct a key,
|
|
this can also be used to migrate files to use the new key format.
|
|
|
|
* map
|
|
|
|
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).
|
|
|
|
Note that this 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.
|
|
|
|
* unannex [path ...]
|
|
|
|
Use this to undo an accidental `git annex add` command. You can use
|
|
`git annex unannex` to move content out of the annex at any point,
|
|
even if you've already committed it.
|
|
|
|
This is not the command you should use if you intentionally annexed a
|
|
file and don't want its contents any more. In that case you should use
|
|
`git annex drop` instead, and you can also `git rm` the file.
|
|
|
|
* uninit
|
|
|
|
Use this to stop using git annex. It will unannex every file in the
|
|
repository, and remove all of git-annex's other data, leaving you with a
|
|
git repository plus the previously annexed files.
|
|
|
|
* fix [path ...]
|
|
|
|
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.
|
|
|
|
* pre-commit [path ...]
|
|
|
|
Fixes up symlinks that are staged as part of a commit, to ensure they
|
|
point to annexed content. Also handles injecting changes to unlocked
|
|
files into the annex.
|
|
|
|
This is meant to be called from git's pre-commit hook. `git annex init`
|
|
automatically creates a pre-commit hook using this.
|
|
|
|
* trust [repository ...]
|
|
|
|
Records that a repository is [[trusted|trust]] to not unexpectedly lose
|
|
content. Use with care.
|
|
|
|
To trust the current repository, use "."
|
|
|
|
* untrust [repository ...]
|
|
|
|
Records that a repository is [[not trusted|trust]] and could lose content
|
|
at any time.
|
|
|
|
* semitrust [repository ...]
|
|
|
|
Returns a repository to the default [[semi trusted|trust]] state.
|
|
|
|
* fromkey file
|
|
|
|
This can be used to manually set up a file to link to a specified key
|
|
in the key-value backend. How you determine an existing key in the backend
|
|
varies. For the URL backend, the key is based on an URL to the content.
|
|
|
|
Example:
|
|
|
|
git annex fromkey --key=URL--http://www.archive.org/somefile somefile
|
|
|
|
* dropkey [key ...]
|
|
|
|
This plumbing-level command drops the annexed data for the specified
|
|
keys from this repository.
|
|
|
|
This can be used to drop content for arbitrary keys, which do not need
|
|
to have a file in the git repository pointing at them.
|
|
|
|
Example:
|
|
|
|
git annex dropkey SHA1-s10-7da006579dd64330eb2456001fd01948430572f2
|
|
|
|
* setkey file
|
|
|
|
This plumbing-level command sets the annexed data for a key to the content of
|
|
the specified file, and then removes the file.
|
|
|
|
Example:
|
|
|
|
git annex setkey --key=WORM-s3-m1287765018--file /tmp/file
|
|
|
|
* upgrade
|
|
|
|
Upgrades the repository to current layout. Upgrades are done automatically
|
|
whenever a newer git annex encounters an old repository; this command
|
|
allows explcitly starting an upgrade.
|
|
|
|
* version
|
|
|
|
Shows the version of git-annex, as well as repository version information.
|
|
|
|
# OPTIONS
|
|
|
|
* --force
|
|
|
|
Force unsafe actions, such as dropping a file's content when no other
|
|
source of it can be verified to still exist. Use with care.
|
|
|
|
* --fast
|
|
|
|
Enables less expensive, but also less thorough versions of some commands.
|
|
What is avoided depends on the command.
|
|
|
|
* --quiet
|
|
|
|
Avoid the default verbose logging of what is done; only show errors
|
|
and progress displays.
|
|
|
|
* --verbose
|
|
|
|
Enable verbose logging.
|
|
|
|
* --from=repository
|
|
|
|
Specifies a repository that content will be retrieved from.
|
|
It should be specified using the name of a configured git remote.
|
|
|
|
* --to=repository
|
|
|
|
Specifies a git repository that content will be sent to.
|
|
It should be specified using the name of a configured git remote.
|
|
|
|
* --exclude=glob
|
|
|
|
Skips files matching the glob pattern. The glob is matched relative to
|
|
the current directory.
|
|
|
|
This option can be specified multiple times.
|
|
|
|
* --backend=name
|
|
|
|
Specifies which key-value backend to use. This can be used when
|
|
adding a file to the annex, or migrating a file. Once files
|
|
are in the annex, their backend is known and this option is not
|
|
necessary.
|
|
|
|
* --key=name
|
|
|
|
Specifies a key to operate on.
|
|
|
|
# CONFIGURATION
|
|
|
|
Like other git commands, git-annex is configured via `.git/config`.
|
|
Here are all the supported configuration settings.
|
|
|
|
* `annex.uuid`
|
|
|
|
A unique UUID for this repository (automatically set).
|
|
|
|
* `annex.numcopies`
|
|
|
|
Number of copies of files to keep across all repositories. (default: 1)
|
|
|
|
* `annex.backends`
|
|
|
|
Space-separated list of names of the key-value backends to use.
|
|
The first listed is used to store new files by default.
|
|
(default: "WORM SHA1 URL")
|
|
|
|
* `remote.<name>.annex-cost`
|
|
|
|
When determining which repository to
|
|
transfer annexed files from or to, ones with lower costs are preferred.
|
|
The default cost is 100 for local repositories, and 200 for remote
|
|
repositories.
|
|
|
|
* `remote.<name>.annex-ignore`
|
|
|
|
If set to `true`, prevents git-annex
|
|
from using this remote by default. (You can still request it be used
|
|
by the --from and --to options.)
|
|
|
|
This is, for example, useful if the remote is located somewhere
|
|
without [[git-annex-shell]]. (For example, if it's on GitHub).
|
|
Or, it could be used if the network connection between two
|
|
repositories is too slow to be used normally.
|
|
|
|
* `remote.<name>.annex-uuid`
|
|
|
|
git-annex caches UUIDs of repositories here.
|
|
|
|
* `remote.<name>.annex-ssh-options`
|
|
|
|
Options to use when using ssh to talk to this repository.
|
|
|
|
* `remote.<name>.annex-rsync-options`
|
|
|
|
Options to use when using rsync
|
|
to or from this repository. For example, to force ipv6, and limit
|
|
the bandwidth to 100Kbyte/s, set it to "-6 --bwlimit 100"
|
|
|
|
* `annex.ssh-options`, `annex.rsync-options`
|
|
|
|
Default ssh and rsync options to use if a remote does not have
|
|
specific options.
|
|
|
|
* `remote.<name>.annex-s3-access-key-id`
|
|
|
|
Your S3 Access Key ID. Does not need to be kept private.
|
|
If not set, the environment variable `AWS_ACCESS_KEY_ID`
|
|
will be used.
|
|
|
|
* `remote.<name>.annex-s3-secret-access-key`
|
|
|
|
Your S3 Secret Access Key. This is a password.
|
|
If not set, the environment variable `AWS_SECRET_ACCESS_KEY`
|
|
will be used.
|
|
|
|
* `remote.<name>.annex-s3-storageclass`
|
|
|
|
Storage class to use when adding new content to S3. The default
|
|
is "STANDARD". If you have configured git-annex to preserve
|
|
multiple [[copies]], consider setting this to "REDUCED_REDUNDANCY"
|
|
to save money.
|
|
|
|
* `annex.diskreserve`
|
|
|
|
Amount of disk space to reserve. Disk space is checked when transferring
|
|
content to avoid running out, and additional free space can be reserved
|
|
via this option, to make space for more important content (such as git
|
|
commit logs). Can be specified with any commonly used units, for example,
|
|
"0.5 gb" or "100 KiloBytes"
|
|
|
|
The default reserve is 1 megabyte.
|
|
|
|
* `annex.version`
|
|
|
|
Automatically maintained, and used to automate upgrades between versions.
|
|
|
|
|
|
|
|
# CONFIGURATION VIA .gitattributes
|
|
|
|
The backend used when adding a new file to the annex can be configured
|
|
on a per-file-type basis via `.gitattributes` files. In the file,
|
|
the `annex.backend` attribute can be set to the name of the backend to
|
|
use. For example, this here's how to use the WORM backend by default,
|
|
but the SHA1 backend for ogg files:
|
|
|
|
* annex.backend=WORM
|
|
*.ogg annex.backend=SHA1
|
|
|
|
The numcopies setting can also be configured on a per-file-type basis via
|
|
the `annex.numcopies` attribute in `.gitattributes` files.
|
|
For example, this makes two copies be needed for wav files:
|
|
|
|
*.wav annex.numcopies=2
|
|
|
|
# FILES
|
|
|
|
These files are used by git-annex, in your git repository:
|
|
|
|
`.git/annex/objects/` contains the annexed file contents that are currently
|
|
available. Annexed files in your git repository symlink to that content.
|
|
|
|
`.git-annex/uuid.log` is used to map between repository UUID and
|
|
descriptions.
|
|
|
|
`.git-annex/trust.log` is used to indicate which repositories are trusted
|
|
and untrusted.
|
|
|
|
`.git-annex/*.log` is where git-annex records its content tracking
|
|
information. These files should be committed to git.
|
|
|
|
`.gitattributes` is configured to use git's union merge driver
|
|
to avoid conflicts when merging files in the `.git-annex` directory.
|
|
|
|
# SEE ALSO
|
|
|
|
Most of git-annex's 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
|
|
should be included, in, for example, `/usr/share/doc/git-annex/`
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <joey@kitenet.net>
|
|
|
|
<http://git-annex.branchable.com/>
|
|
|
|
Warning: this page is automatically made into a man page via [mdwn2man](http://git.ikiwiki.info/?p=ikiwiki;a=blob;f=mdwn2man;hb=HEAD). Edit with care
|