314 lines
11 KiB
Markdown
314 lines
11 KiB
Markdown
# NAME
|
|
|
|
git-annex - manage files with git, without checking their contents in
|
|
|
|
# SYNOPSIS
|
|
|
|
git annex subcommand [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
|
|
|
|
# SUBCOMMANDS
|
|
|
|
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.
|
|
|
|
Many git-annex subcommands 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.
|
|
|
|
* 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 subcommand. May be easier to remember,
|
|
if you think of this as allowing you to edit an annexed file.
|
|
|
|
* move [path ...]
|
|
|
|
When used with the --to option, moves the content of annexed files from
|
|
the current repository to the specified one.
|
|
|
|
When used with the --from option, moves the content of annexed files
|
|
from the specified repository to the current one.
|
|
|
|
* copy [path ...]
|
|
|
|
When used with the --to option, copies the content of annexed files from
|
|
the current repository to the specified one.
|
|
|
|
When used with the --from option, copies the content of annexed files
|
|
from the specified repository to the current one.
|
|
|
|
* init description
|
|
|
|
Initializes git-annex with a description of the git repository,
|
|
and sets up `.gitattributes` and the pre-commit hook.
|
|
|
|
* 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.
|
|
|
|
* fsck [path ...]
|
|
|
|
With no parameters, this subcommand checks the whole annex for consistency,
|
|
and warns about any problems found.
|
|
|
|
With parameters, only the specified files are checked.
|
|
|
|
* 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.
|
|
|
|
* 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.
|
|
|
|
* unannex [path ...]
|
|
|
|
Use this to undo an accidental add command. 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.
|
|
|
|
* 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.
|
|
|
|
* fromkey file
|
|
|
|
This can be used to maually 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 just a URL to the content.
|
|
|
|
Example:
|
|
|
|
git annex fromkey --backend=URL --key=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.
|
|
|
|
A backend will typically need to be specified with --backend. If none
|
|
is specified, the first configured backend is used.
|
|
|
|
Example:
|
|
|
|
git annex dropkey --backend=SHA1 7da006579dd64330eb2456001fd01948430572f2
|
|
|
|
* setkey file
|
|
|
|
This plumbing-level command sets the annxed data for a key to the content of
|
|
the specified file, and then removes the file.
|
|
|
|
A backend will typically need to be specified with --backend. If none
|
|
is specified, the first configured backend is used.
|
|
|
|
Example:
|
|
|
|
git annex setkey --backend=WORM --key=1287765018:3 /tmp/file
|
|
|
|
# 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.
|
|
|
|
* --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.
|
|
|
|
* --backend=name
|
|
|
|
Specifies which key-value backend to use.
|
|
|
|
* --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 ever using this remote. This is, for example, useful if the
|
|
remote is a bare repository, which git-annex does not currently support.
|
|
* `remote.<name>.annex-uuid` -- git-annex caches UUIDs of repositories
|
|
here.
|
|
* `remote.<name>.annex-scp-options` -- Options to use when using scp
|
|
to or from this repository. For example, to force ipv6, and limit
|
|
the bandwidth to 100Kbit/s, set it to "-6 -l 100"
|
|
* `remote.<name>.annex-ssh-options` -- Options to use when using ssh
|
|
to talk to this repository.
|
|
* `annex.scp-options` and `annex.ssh-options` -- Default scp and ssh
|
|
options to use if a remote does not have specific options.
|
|
* `annex.version` -- Automatically maintained, and used to automate upgrades
|
|
between versions.
|
|
|
|
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 `git-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:
|
|
|
|
* git-annex-backend=WORM
|
|
*.ogg git-annex-backend=SHA1
|
|
|
|
The numcopies setting can also be configured on a per-file-type basis via
|
|
the `git-annex-numcopies` attribute in `.gitattributes` files.
|
|
For example, this makes two copies be needed for wav files:
|
|
|
|
*.wav git-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
|
|
decscriptions. You may edit it.
|
|
|
|
`.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
|