git‐annex − manage files with git, without checking their
contents in

git annex command [params ...]

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

     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.

 # git annex get video/
 get video/ (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
     58d84e8a−d9ae−11df−a1aa−ab9aa8c00826  −− portable USB
     ca20064c−dbb5−11df−b2fe−002170d25c55  −− backup SATA
 # sudo mount /media/usb
 # git remote add usbdrive /media/usb
 # git annex get video/
 get video/ (from usbdrive...) ok

 # git annex add iso
 add iso/Debian_5.0.iso ok

 # git annex drop iso/Debian_4.0.iso
 drop iso/Debian_4.0.iso ok


 # git annex move iso −−to=usbdrive
 move iso/Debian_5.0.iso (moving to usbdrive...) ok


     Display built−in help.

     For help on a specific command, use git annex help

add [path ...]
     Adds files to the annex.

     See git‐annex−add(1) for details.

get [path ...]
     Makes the content of annexed files available in this

     See git‐annex−get(1) for details.

drop [path ...]
     Drops the content of annexed files from this

     See git‐annex−drop(1) for details.

move [path ...] [−−from=remote|−−to=remote]
     Moves the content of files from or to another remote.

     See git‐annex−move(1) for details.

copy [path ...] [−−from=remote|−−to=remote]
     Copies the content of files from or to another remote.

     See git‐annex−copy(1) for details.

status [path ...]
     Similar to git status −−short, displays the status of
     the files in the working tree.

     See git‐annex−status(1) for details.


unlock [path ...]
     Unlock annexed files for modification.

     See git‐annex−unlock(1) for details.

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.

     See git‐annex−lock(1) for details.

sync [remote ...]
     Synchronize local repository with remotes.

     See git‐annex−sync(1) for details.

mirror [path ...] [−−to=remote|−−from=remote]
     Mirror content of files to/from another repository.

     See git‐annex−mirror(1) for details.

addurl [url ...]
     Downloads each url to its own file, which is added to
     the annex.

     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 −−from remote branch[:subdir] | [path ...]
     Add a tree of files to the repository.

     See git‐annex−import(1) for details.

importfeed [url ...]
     Imports the contents of podcast feeds into the annex.


     See git‐annex−importfeed(1) for details.

export treeish −−to remote
     Export content to a remote.

     See git‐annex−export(1) for details.

undo [filename|directory] ...
     Undo last change to a file or directory.

     See git‐annex−undo(1) for details.

     Multicast file distribution.

     See git‐annex−multicast(1) for details.

     Watch for changes and autocommit.

     See git‐annex−watch(1) for details.

     Automatically sync folders between devices.

     See git‐annex−assistant(1) for details.

     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

     See git‐annex−webapp(1) for details.

     Persistant communication with remotes.

     See git‐annex−remotedaemon(1) for details.

init [description]

     Until a repository (or one of its remotes) has been
     initialized, git‐annex will refuse to operate on it, to


     avoid accidentally using it in a repository that was
     not intended to have an annex.

     See git‐annex−init(1) for details.

describe repository description
     Changes the description of a repository.

     See git‐annex−describe(1) for details.

initremote name type=value [param=value ...]
     Creates a new special remote, and adds it to

     See git‐annex−initremote(1) for details.

enableremote name [param=value ...]
     Enables use of an existing special remote in the
     current repository.

     See git‐annex−enableremote(1) for details.

     Renames a special remote.

     See git‐annex−renameremote(1) for details.

     Sets up tor hidden service.

     See git‐annex−enable−tor(1) for details.

numcopies [N]
     Configure desired number of copies.

     See git‐annex−numcopies(1) for details.

trust [repository ...]
     Records that a repository is trusted to not
     unexpectedly lose content. Use with care.

     See git‐annex−trust(1) for details.

untrust [repository ...]
     Records that a repository is not trusted and could lose
     content at any time.


     See git‐annex−untrust(1) for details.

semitrust [repository ...]
     Returns a repository to the default semi trusted state.

     See git‐annex−semitrust(1) for details.

group repository groupname
     Add a repository to a group.

     See git‐annex−group(1) for details.

ungroup repository groupname
     Removes a repository from a group.

     See git‐annex−ungroup(1) for details.

wanted repository [expression]
     Get or set preferred content expression.

     See git‐annex−wanted(1) for details.

groupwanted groupname [expression]
     Get or set groupwanted expression.

     See git‐annex−groupwanted(1) for details.

required repository [expression]
     Get or set required content expression.

     See git‐annex−required(1) for details.

schedule repository [expression]
     Get or set scheduled jobs.

     See git‐annex−schedule(1) for details.

     Get and set other configuration stored in git‐annex

     See git‐annex−config(1) for details.

     Opens EDITOR on a temp file containing most of the


     above configuration settings, as well as a few others,
     and when it exits, stores any changes made back to the
     git‐annex branch.

     See git‐annex−vicfg(1) for details.

     Switches a repository to use an adjusted branch, which
     can automatically unlock all files, etc.

     See git‐annex−adjust(1) for details.

     Switches a repository to use direct mode. (deprecated)

     See git‐annex−direct(1) for details.

     Switches a repository to use indirect mode.

     See git‐annex−indirect(1) for details.

fsck [path ...]

     Checks the annex consistency, and warns about or fixes
     any problems found.  This is a good complement to git

     See git‐annex−fsck(1) for details.

expire [repository:]time ...
     Expires repositories that have not recently performed
     an activity (such as a fsck).

     See git‐annex−expire(1) for details.

     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.

     See git‐annex−unused(1) for details.


dropunused [number|range ...]
     Drops the data corresponding to the numbers, as listed
     by the last git annex unused

     See git‐annex−dropunused(1) for details.

addunused [number|range ...]
     Adds back files for the content corresponding to the
     numbers or ranges, as listed by the last git annex

     See git‐annex−addunused(1) for details.

fix [path ...]
     Fixes up symlinks that have become broken to again
     point to annexed content.

     See git‐annex−fix(1) for details.

     Automatically merge changes from remotes.

     See git‐annex−merge(1) for details.

     Upgrades the repository.

     See git‐annex−upgrade(1) for details.

dead [repository ...] [−−key key]
     Indicates that a repository or a single key has been
     irretrievably lost.

     See git‐annex−dead(1) for details.

     Causes the git‐annex branch to be rewritten, throwing
     away historical data about past locations of files.

     See git‐annex−forget(1) for details.

     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.

     See git‐annex−repair(1) for details.

p2p  Configure peer−2−Peer links between repositories.

     See git‐annex−p2p(1) for details.

find [path ...]

     Outputs a list of annexed files in the specified path.
     With no path, finds files in the current directory and
     its subdirectories.

     See git‐annex−find(1) for details.

whereis [path ...]
     Displays information about where the contents of files
     are located.

     See git‐annex−whereis(1) for details.

list [path ...]
     Displays a table of remotes that contain the contents
     of the specified files. This is similar to whereis but
     a more compact display.

     See git‐annex−list(1) for details.

log [path ...]
     Displays the location log for the specified file or
     files, showing each repository they were added to ("+")
     and removed from ("−").

     See git‐annex−log(1) for details.

info [directory|file|remote|uuid ...]
     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.

     See git‐annex−info(1) for details.


     Shows the version of git‐annex, as well as repository
     version information.

     See git‐annex−version(1) for details.

map  Generate map of repositories.

     See git‐annex−map(1) for details.

     Access files while they’re being downloaded.

     See git‐annex−inprogress(1) for details.

metadata [path ...]

     The content of an annexed file can have any number of
     metadata fields attached to it to describe it. Each
     metadata field can in turn have any number of values.

     This command can be used to set metadata, or show the
     currently set metadata.

     See git‐annex−metadata(1) for details.

view [tag ...] [field=value ...] [field=glob ...] [!tag ...]
     [field!=value ...]
     Uses metadata to build a view branch of the files in
     the current branch, and checks out the view branch.
     Only files in the current branch whose metadata matches
     all the specified field values and tags will be shown
     in the view.

     See git‐annex−view(1) for details.

vpop [N]
     Switches from the currently active view back to the
     previous view.  Or, from the first view back to
     original branch.

     See git‐annex−vpop(1) for details.

vfilter [tag ...] [field=value ...] [!tag ...] [field!=value
     Filters the current view to only the files that have


     the specified field values and tags.

     See git‐annex−vfilter(1) for details.

vadd [field=glob ...] [field=value ...] [tag ...]
     Changes the current view, adding an additional level of
     directories to categorize the files.

     See git‐annex−vfilter(1) for details.

     When a view involves nested subdirectories, this cycles
     the order.

     See git‐annex−vcycle(1) for details.

migrate [path ...]

     Changes the specified annexed files to use a different
     key−value backend.

     See git‐annex−migrate(1) for details.

reinject src dest
     Moves the src file into the annex as the content of the
     dest file.  This can be useful if you have obtained the
     content of a file from elsewhere and want to put it in
     the local annex.

     See git‐annex−reinject(1) for details.

unannex [path ...]
     Use this to undo an accidental git annex add command.
     It puts the file back how it was before the add.

     See git‐annex−unannex(1) for details.

     De−initialize git‐annex and clean out repository.

     See git‐annex−uninit(1) for details.

reinit uuid|description
     Initialize repository, reusing old UUID.


     See git‐annex−reinit(1) for details.

pre−commit [path ...]

     This is meant to be called from git’s pre−commit hook.
     git annex init automatically creates a pre−commit hook
     using this.

     See git‐annex−pre−commit(1) for details.

     This is meant to be called from git’s post−receive
     hook. git annex init automatically creates a
     post−receive hook using this.

     See git‐annex−post−receive(1) for details.

lookupkey [file ...]
     Looks up key used for file.

     See git‐annex−lookupkey(1) for details.

calckey [file ...]
     Calculates the key that would be used to refer to a

     See git‐annex−calckey(1) for details.

contentlocation [key ..]
     Looks up location of annexed content for a key.

     See git‐annex−contentlocation(1) for details.

examinekey [key ...]
     Print information that can be determined purely by
     looking at the key.

     See git‐annex−examinekey(1) for details.

     Checks if a preferred content expression matches
     provided data.

     See git‐annex−matchexpression(1) for details.


fromkey [key file]
     Manually set up a file in the git repository to link to
     a specified key.

     See git‐annex−fromkey(1) for details.

registerurl [key url]
     Registers an url for a key.

     See git‐annex−registerurl(1) for details.

setkey key file
     Moves a file into the annex as the content of a key.

     See git‐annex−setkey(1) for details.

dropkey [key ...]
     Drops annexed content for specified keys.

     See git‐annex−dropkey(1) for details.

transferkey key [−−from=remote|−−to=remote]
     Transfers a key from or to a remote.

     See git‐annex−transferkey(1) for details.

     Used internally by the assistant.

     See git‐annex−transferkey(1) for details.

setpresentkey key uuid [1|0]
     This plumbing−level command changes git‐annex’s records
     about whether the specified key’s content is present in
     a remote with the specified uuid.

     See git‐annex−setpresentkey(1) for details.

readpresentkey key uuid
     Read records of where key is present.

     See git‐annex−readpresentkey(1) for details.

checkpresentkey key remote
     Check if key is present in remote.


     See git‐annex−checkpresentkey(1) for details.

rekey [file key ...]
     Change keys used for files.

     See git‐annex−rekey(1) for details.

     Resolves a conflicted merge, by adding both conflicting
     versions of the file to the tree, using variants of
     their filename. This is done automatically when using
     git annex sync or git annex merge.

     See git‐annex−resolvemerge(1) for details.

     This can be used to make git diff use an external diff
     driver with annexed files.

     See git‐annex−diffdriver(1) for details.

     This command lets git‐annex be used as a git filter
     driver, allowing annexed files in the git repository to
     be unlocked at all times, instead of being symlinks.

     See git‐annex−smudge(1) for details.

findref [ref]
     Lists files in a git ref. (deprecated)

     See git‐annex−findref(1) for details.

proxy −− git cmd [options]
     Bypass direct mode guard. (deprecated)

     See git‐annex−proxy(1) for details.


     This runs git‐annex’s built−in test suite.

     See git‐annex−test(1) for details.


testremote remote
     This tests a remote by generating some random objects
     and sending them to the remote, then redownloading
     them, removing them from the remote, etc.

     It’s safe to run in an existing repository (the
     repository contents are not altered), although it may
     perform expensive data transfers.

     See git‐annex−testremote(1) for details.

     Generates random changes to files in the current
     repository, for use in testing the assistant.

     See git‐annex−fuzztest(1) for details.

     This runs git‐annex’s built−in benchmarks, if it was
     built with benchmarking support.

     See git‐annex−benchmark(1) for details.

These common options are accepted by all git‐annex commands,
and may not be explicitly listed on their individual man
pages.  (Many commands also accept the git‐

     Force unsafe actions, such as dropping a file’s content
     when no other source of it can be verified to still
     exist, or adding ignored files.  Use with care.

     Enable less expensive, but also less thorough versions
     of some commands.  What is avoided depends on the

     Avoid the default verbose display of what is done; only
     show errors.

     Enable verbose display.


     Show debug messages.

     Disable debug messages.

     Overrides the numcopies setting, forcing git‐annex to
     ensure the specified number of copies exist.

     Note that setting numcopies to 0 is very unsafe.

     Limits how long a git‐annex command runs. The time can
     be something like "5h", or "30m" or even "45s" or

     Note that git‐annex may continue running a little past
     the specified time limit, in order to finish processing
     a file.

     Also, note that if the time limit prevents git‐annex
     from doing all it was asked to, it will exit with a
     special code, 101.



     Overrides trust settings for a repository. May be
     specified more than once.

     The repository should be specified using the name of a
     configured remote, or the UUID or description of a

     Amazon Glacier inventories take hours to retrieve, and
     may not represent the current state of a repository. So
     git‐annex does not trust that files that the inventory
     claims are in Glacier are really there.  This switch
     can be used to allow it to trust the inventory.

     Be careful using this, especially if you or someone
     else might have recently removed a file from Glacier.
     If you try to drop the only other copy of the file, and
     this switch is enabled, you could lose data!


     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.

     Overrides the User−Agent to use when downloading files
     from the web.

     Caused a desktop notification to be displayed after
     each successful file download and upload.

     (Only supported on some platforms, e.g. Linux with
     dbus. A no−op when not supported.)

     Caused a desktop notification to be displayed when a
     file upload or download has started, or when a file is

−c name=value
     Overrides git configuration settings. May be specified
     multiple times.

Like other git commands, git‐annex is configured via

     A unique UUID for this repository (automatically set).

     Name of the default key−value backend to use when
     adding new files to the repository.

     This is overridden by annex annex.backend configuration
     in the .gitattributes files, and by the −−backend

     (This used to be named annex.backends, and that will
     still be used if set.)

     Set to true to indicate that the repository should only
     use cryptographically secure hashes (SHA2, SHA3) and


     not insecure hashes (MD5, SHA1) for content.

     When this is set, the contents of files using
     cryptographically insecure hashes will not be allowed
     to be added to the repository.

     Also, git‐annex fsck will complain about any files
     present in the repository that use insecure hashes.
     And, git‐annex import −−no−content will refuse to
     import files from special remotes using insecure

     To configure the behavior in new clones of the
     repository, this can be set using git‐annex−config.

     Maximum length, in bytes, of what is considered a
     filename extension when adding a file to a backend that
     preserves filename extensions. The default length is 4,
     which allows extensions like "jpeg". The dot before the
     extension is not counted part of its length. At most
     two extensions at the end of a filename will be
     preserved, e.g. .gz or .tar.gz .

     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", "500M", or "100

     The default reserve is 1 megabyte.

     Set to true to make commands like "git‐annex get"
     silently skip over items that are listed in the command
     line, but are not checked into git.

     Set to false to make it an error for commands like
     "git‐annex get" to be asked to operate on files that
     are not checked into git.

     The default is currently true, but is planned to change
     to false in a release in 2022.

     Note that, when annex.skipunknown is false, a command
     like "git‐annex get ."  will fail if no files in the
     current directory are checked into git, but a command
     like "git‐annex get" will not fail, because the current


     directory is not listed, but is implicit. Commands like
     "git‐annex get foo/" will fail if no files in the
     directory are checked into git, but if at least one
     file is, it will ignore other files that are not. This
     is all the same as the behavior of "git−ls files

     Also note that git‐annex skips files that are checked
     into git, but are not annexed files, this setting does
     not affect that.

     Used to configure which files are large enough to be
     added to the annex.  It is an expression that matches
     the large files, eg "include=*.mp3 or
     largerthan(500kb)" See git‐annex−matching−expression(1)
     for details on the syntax.

     Overrides any annex.largefiles attributes in
     .gitattributes files.

     To configure a default annex.largefiles for all clones
     of the repository, this can be set in git‐

     This configures the behavior of both git‐annex and git
     when adding files to the repository. By default, git‐
     annex add adds all files to the annex (except
     dotfiles), and git add adds files to git (unless they
     were added to the annex previously).  When
     annex.largefiles is configured, both git annex add and
     git add will add matching large files to the annex, and
     the other files to git.

     Other git‐annex commands also honor annex.largefiles,
     including git annex import, git annex addurl, git annex
     importfeed and the assistant.

     Normally, dotfiles are assumed to be files like
     .gitignore, whose content should always be part of the
     git repository, so they will not be added to the annex.
     Setting annex.dotfiles to true makes dotfiles be added
     to the annex the same as any other file.

     To annex only some dotfiles, set this and configure
     annex.largefiles to match the ones you want. For
     example, to match only dotfiles ending in ".big"

      git config annex.largefiles "(include=.*.big or
     include=*/.*.big) or (exclude=.* and exclude=*/.*)"
      git config annex.dotfiles true


     To configure a default annex.dotfiles for all clones of
     the repository, this can be set in git‐annex−config(1).

     Setting this to false will prevent git add from adding
     files to the annex, despite the annex.largefiles

     Controls whether small files (not matching
     annex.largefiles) should be checked into git by git
     annex add. Defaults to true; set to false to instead
     make small files be skipped.

     Commands like git‐annex add default to adding files to
     the repository in locked form. This can make them add
     the files in unlocked form, the same as if git‐
     annex−unlock(1) were run on the files.

     This can be set to "true" to add everything unlocked,
     or it can be a more complicated expression that matches
     files by name, size, or content. See git‐
     annex−matching−expression(1) for details.

     To configure a default annex.addunlocked for all clones
     of the repository, this can be set in git‐

     (Using git add always adds files in unlocked form and
     it is not affected by this setting.)

     When a repository has core.symlinks set to false, or
     has an adjusted unlocked branch checked out, this
     setting is ignored, and files are always added to the
     repository in unlocked form.

     This is a deprecated setting. You should instead use
     the git annex numcopies command to configure how many
     copies of files are kept across all repositories, or
     the annex.numcopies .gitattributes setting.

     This config setting is only looked at when git annex
     numcopies has never been configured, and when there’s
     no annex.numcopies setting in the .gitattributes file.

     Note that setting numcopies to 0 is very unsafe.


     Set this to true to make git‐annex automatically
     generate some metadata when adding files to the

     In particular, it stores year, month, and day metadata,
     from the file’s modification date.

     When importfeed is used, it stores additional metadata
     from the feed, such as the author, title, etc.

     This controls which refs git‐annex unused considers to
     be used.  See REFSPEC FORMAT in git‐annex−unused(1) for
     Configure the number of concurrent jobs to run. Default
     is 1.

     Only git‐annex commands that support the −−jobs option
     will use this.

     Setting this to "cpus" will run one job per CPU core.

     git‐annex builds a queue of git commands, in order to
     combine similar commands for speed. By default the size
     of the queue is limited to 10240 commands; this can be
     used to change the size. If you have plenty of memory
     and are working with very large numbers of files,
     increasing the queue size can speed it up.

     The git annex unused and git annex sync −−content
     commands use a bloom filter to determine what files are
     present in eg, the work tree.  The default bloom filter
     is sized to handle up to 500000 files. If your
     repository is larger than that, you should increase
     this value. Larger values will make git‐annex unused
     and git annex sync −−content consume more memory; run
     git annex info for memory usage numbers.

     Adjusts the accuracy of the bloom filter used by git
     annex unused and git annex sync −−content.  The default
     accuracy is 10000000 −− 1 unused file out of 10000000
     will be missed by git annex unused. Increasing the
     accuracy will make git annex unused consume more


     memory; run git annex info for memory usage numbers.

     By default, git‐annex caches ssh connections using
     ssh’s ControlMaster and ControlPersist settings (if
     built using a new enough ssh). To disable this, set to

     By default, git‐annex automatically commits data to the
     git‐annex branch after each command is run. If you have
     a series of commands that you want to make a single
     commit, you can run the commands with −c
     annex.alwayscommit=false. You can later commit the data
     by running git annex merge (or by automatic merges) or
     git annex sync.

     When git‐annex updates the git‐annex branch, it usually
     makes up its own commit message ("update"), since users
     rarely look at or care about changes to that branch. If
     you do care, you can specify this setting by running
     commands with −c annex.commitmessage=whatever

     This works well in combination with
     annex.alwayscommit=false, to gather up a set of changes
     and commit them with a message you specify.

     By default git‐annex avoids gpg signing commits that it
     makes when they’re not the purpose of a command, but
     only a side effect.  That default avoids lots of gpg
     password prompts when commit.gpgSign is set. A command
     like git annex sync or git annex merge will gpg sign
     its commit, but a command like git annex get, that
     updates the git‐annex branch, will not. The assistant
     also avoids signing commits.

     Setting annex.allowsign to true lets all commits be
     signed, as controlled by commit.gpgSign and other git

     By default, git‐annex branches that have been pulled
     from remotes are automatically merged into the local
     git‐annex branch, so that git‐annex has the most
     up−to−date possible knowledge.


     To avoid that merging, set this to "false". This can be
     useful particularly when you don’t have write
     permission to the repository.

     Set this to true to make file contents be hard linked
     between the repository and its remotes when possible,
     instead of a more expensive copy.

     Use with caution −− This can invalidate numcopies
     counting, since with hard links, fewer copies of a file
     can exist. So, it is a good idea to mark a repository
     using this setting as untrusted.

     When a repository is set up using git clone −−shared,
     git‐annex init will automatically set annex.hardlink
     and mark the repository as untrusted.

     Set this to true to make unlocked files be a hard link
     to their content in the annex, rather than a second
     copy. This can save considerable disk space, but when a
     modification is made to a file, you will lose the local
     (and possibly only) copy of the old version. So, enable
     with care.

     After setting (or unsetting) this, you should run git
     annex fix to fix up the annexed files in the work tree
     to be hard links (or copies).

     Note that this has no effect when the filesystem does
     not support hard links.  And when multiple files in the
     work tree have the same content, only one of them gets
     hard linked to the annex.

     Set to false to prevent merge conflicts in the checked
     out branch being automatically resolved by the git‐
     annex assitant, git‐annex sync, git‐annex merge, and
     the git‐annex post−receive hook.

     To configure the behavior in all clones of the
     repository, this can be set in git‐annex−config(1).

     Set to true to make git‐annex sync default to syncing
     annexed content.

     To configure the behavior in all clones of the
     repository, this can be set in git‐annex−config(1).


     Set to true to make git‐annex sync default to only
     sincing the git‐annex branch and annexed content.

     To configure the behavior in all clones of the
     repository, this can be set in git‐annex−config(1).

     Set to true to enable debug logging by default.

     The current version of the git‐annex repository. This
     is maintained by git‐annex and should never be manually

     When an old git‐annex repository version has become
     deprecated, git‐annex will normally automatically
     upgrade the repository to the new version.

     If this is set to false, git‐annex won’t automatically
     upgrade the repository. Instead it will exit with an
     error message. You can run git annex upgrade yourself
     when you are ready to upgrade the repository.

     Set to true if the repository is on a crippled
     filesystem, such as FAT, which does not support
     symbolic links, or hard links, or unix permissions.
     This is automatically probed by "git annex init".

     Normally, git‐annex uses fine−grained lock files to
     allow multiple processes to run concurrently without
     getting in each others’ way.  That works great, unless
     you are using git‐annex on a filesystem that does not
     support POSIX fcntl locks. This is sometimes the case
     when using NFS or Lustre filesystems.

     To support such situations, you can set annex.pidlock
     to true, and it will fall back to a single top−level
     pid file lock.

     Although, often, you’d really be better off fixing your
     networked filesystem configuration to support POSIX
     locks.. And, some networked filesystems are so
     inconsistent that one node can’t reliably tell when the
     other node is holding a pid lock. Caveat emptor.


     When using pid lock files, it’s possible for a stale
     lock file to get left behind by previous run of git‐
     annex that crashed or was interrupted.  This is mostly
     avoided, but can occur especially when using a network
     file system.

     git‐annex will wait up to this many seconds for the pid
     lock file to go away, and will then abort if it cannot
     continue. Default: 300

     When "true" (the default), git‐annex will cache
     credentials used to access special remotes in files in
     .git/annex/creds/ that only you can read. To disable
     that caching, set to "false", and credentials will only
     be read from the environment, or if they have been
     embedded in encrypted form in the git repository, will
     be extracted and decrypted each time git‐annex needs to
     access the remote.−erase−command
     This can be set to a command that should be run
     whenever git‐annex removes the content of a file from
     the repository.

     In the command line, %file is replaced with the file
     that should be erased.

     For example, to use the wipe command, set it to wipe −f

annex.tune.objecthash1, annex.tune.objecthashlower,
     These can be passed to git annex init to tune the
     repository.  They cannot be safely changed in a running
     repository and should never be set in global git
     configuration.  For details, see <https://git‐>.

Remotes are configured using these settings in .git/config.

     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.


     If set, the command is run, and the number it outputs
     is used as the cost.  This allows varying the cost
     based on e.g., the current network.

     A command to run when git‐annex begins to use the
     remote. This can be used to, for example, mount the
     directory containing the remote.

     The command may be run repeatedly when multiple git‐
     annex processes are running concurrently.

     A command to run when git‐annex is done using the

     The command will only be run once *all* running git‐
     annex processes are finished using the remote.

     Specify an alternative git‐annex−shell executable on
     the remote instead of looking for "git‐annex−shell" on
     the PATH.

     This is useful if the git‐annex−shell program is
     outside the PATH or has a non−standard name.

     If set to true, prevents git‐annex from storing file
     contents on 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.

     This does not prevent git‐annex sync (or the git‐annex
     assistant) from syncing the git repository to the

     If set, the command is run, and if it exits nonzero,
     that’s the same as setting annex−ignore to true. This
     allows controlling behavior based on e.g., the current


     If set to false, prevents git‐annex sync (and the git‐
     annex assistant) from syncing with this remote by
     default. However, git annex sync <name> can still be
     used to sync with the remote.

     If set, the command is run, and if it exits nonzero,
     that’s the same as setting annex−sync to false. This
     allows controlling behavior based on e.g., the current

     If set to false, prevents git‐annex sync (and the git‐
     annex assistant etc) from ever pulling (or fetching)
     from the remote.

     If set to false, prevents git‐annex sync (and the git‐
     annex assistant etc) from ever pushing to the remote.

     If set to true, prevents git‐annex from making changes
     to a remote.  This both prevents git‐annex sync from
     pushing changes, and prevents storing or removing files
     from read−only remote.

remote.<name>.annex−verify, annex.verify
     By default, git‐annex will verify the checksums of
     objects downloaded from remotes. If you trust a remote
     and don’t want the overhead of these checksums, you can
     set this to false.

     Note that even when this is set to false, git‐annex
     does verification in some edge cases, where it’s likely
     the case than an object was downloaded incorrectly, or
     when needed for security.

     This is for use with special remotes that support
     exports and imports.

     When set to eg, "master", this tells git‐annex that you
     want the special remote to track that branch.

     When set to eg, "master:subdir", the special remote
     tracks only the subdirectory of that branch.


     git‐annex sync −−content will import changes from the
     remote and merge them into the annex−tracking−branch.
     They also export changes made to the branch to the

     Deprecated name for
     remote.<name>.annex−tracking−branch. Will still be used
     if it’s configured and
     remote.<name>.annex−tracking−branch is not.

     Can be used to specify a different url than the regular
     remote.<name>.url for git‐annex to use when talking
     with the remote. Similar to the pushUrl used by

     git‐annex caches UUIDs of remote repositories here.

     Used for some special remotes, points to a different
     special remote configuration to use.

remote.<name>.annex−retry, annex.retry
     Configure retries of failed transfers on a per−remote
     and general basis, respectively. The value is the
     number of retries that can be made of the same
     transfer. (default 0)

remote.<name>.annex−retry−delay, annex.retry−delay
     Number of seconds to delay before the first retry of a
     transfer.  When making multiple retries of the same
     transfer, the delay doubles after each retry. (default

     This only affects remotes that have their url pointing
     to a directory on the same system. git‐annex normally
     checks the uuid of such remotes each time it’s run,
     which lets it transparently deal with different drives
     being mounted to the location at different times.

     Setting annex−checkuuid to false will prevent it from
     checking the uuid at startup (although the uuid is
     still verified before making any changes to the remote
     repository). This may be useful to set to prevent


     unncessary spin−up or automounting of a drive.

     Configures a local trust level for the remote. This
     overrides the value configured by the trust and untrust
     commands. The value can be any of "trusted",
     "semitrusted" or "untrusted".

     Can be used to tell git‐annex whether a remote is
     LocallyAvailable or GloballyAvailable. Normally, git‐
     annex determines this automatically.

     Set to "true" to make git‐annex speculate that this
     remote may contain the content of any file, even though
     its normal location tracking does not indicate that it
     does. This will cause git‐annex to try to get all file
     contents from the remote. Can be useful in setting up a
     caching remote.

     Can be used to tell git‐annex if a remote is a bare
     repository or not. Normally, git‐annex determines this

     Options to use when using ssh to talk to this remote.

     Options to use when using rsync to or from this remote.
     For example, to force IPv6, and limit the bandwidth to
     100Kbyte/s, set it to −6 −−bwlimit 100

     Note that git‐annex−shell has a whitelist of allowed
     rsync options, and others will not be be passed to the
     remote rsync. So using some options may break the
     communication between the local and remote rsyncs.

     Options to use when using rsync to upload a file to a

     These options are passed after other applicable rsync
     options, so can be used to override them. For example,
     to limit upload bandwidth to 10Kbyte/s, set −−bwlimit


     Options to use when using rsync to download a file from
     a remote.

     These options are passed after other applicable rsync
     options, so can be used to override them.

     The remote shell to use to connect to the rsync remote.
     Possible values are ssh (the default) and rsh, together
     with their arguments, for instance ssh −p 2222 −c
     blowfish; Note that the remote hostname should not
     appear there, see rsync(1) for details.  When the
     transport used is ssh, connections are automatically
     cached unless annex.sshcaching is unset.

     Options to pass to bup split when storing content in
     this remote.  For example, to limit the bandwidth to
     100Kbyte/s, set it to −−bwlimit 100k (There is no
     corresponding option for bup join.)

     Options to pass to GnuPG when it’s encrypting data. For
     instance, to use the AES cipher with a 256 bits key and
     disable compression, set it to −−cipher−algo AES256
     −−compress−algo none. (These options take precedence
     over the default GnuPG configuration, which is
     otherwise used.)

     Options to pass to GnuPG when it’s decrypting data.
     (These options take precedence over the default GnuPG
     configuration, which is otherwise used.)

annex.ssh−options, annex.rsync−options,
     annex.rsync−download−options, annex.bup−split−options,
     annex.gnupg−options, annex.gnupg−decrypt−options

     Default options to use if a remote does not have more
     specific options as described above.

     Used by rsync special remotes, this configures the
     location of the rsync repository to use. Normally this
     is automatically set up by git annex initremote, but
     you can change it if needed.


     Used by bup special remotes, this configures the
     location of the bup repository to use. Normally this is
     automatically set up by git annex initremote, but you
     can change it if needed.

     Used by ddar special remotes, this configures the
     location of the ddar repository to use. Normally this
     is automatically set up by git annex initremote, but
     you can change it if needed.

     Used by directory special remotes, this configures the
     location of the directory where annexed files are
     stored for this remote. Normally this is automatically
     set up by git annex initremote, but you can change it
     if needed.

     Used to identify remotes on Android devices accessed
     via adb.  Normally this is automatically set up by git
     annex initremote.

     Used by adb special remotes, this is the directory on
     the Android device where files are stored for this
     remote. Normally this is automatically set up by git
     annex initremote, but you can change it if needed.

     Used by adb special remotes, this is the serial number
     of the Android device used by the remote. Normally this
     is automatically set up by git annex initremote, but
     you can change it if needed, eg when upgrading to a new
     Android device.

     Used to identify Amazon S3 special remotes.  Normally
     this is automatically set up by git annex initremote.

     Used to identify Amazon Glacier special remotes.
     Normally this is automatically set up by git annex


     Used to identify webdav special remotes.  Normally this
     is automatically set up by git annex initremote.

     Used to identify tahoe special remotes.  Points to the
     configuration directory for tahoe.

     Used to identify gcrypt special remotes.  Normally this
     is automatically set up by git annex initremote.

     It is set to "true" if this is a gcrypt remote.  If the
     gcrypt remote is accessible over ssh and has git‐
     annex−shell available to manage it, it’s set to

     Used to identify git−lfs special remotes.  Normally
     this is automatically set up by git annex initremote.

     It is set to "true" if this is a git−lfs remote.

     Used external special remotes to record the type of the

     Eg, if this is set to "foo", git‐annex will run a "git‐
     annex−remote−foo" program to communicate with the
     external special remote.

     If this is set to "readonly", then git‐annex will not
     run any external special remote program, but will try
     to access things stored in the remote using http. That
     only works for some external special remotes, so
     consult the documentation of the one you are using.

     Used by hook special remotes to record the type of the

     Options to pass to curl when git‐annex uses it to
     download urls (rather than the default built−in url

     For example, to force IPv4 only, set it to "−4".  Or to
     make curl use your ~/.netrc file, set it to "−−netrc".


     Setting this option makes git‐annex use curl, but only
     when−ip−addresses is configured
     in a specific way. See its documentation.−dl−options
     Options to pass to youtube−dl when using it to find the
     url to download for a video.

     Some options may break git‐annex’s integration with
     youtube−dl. For example, the −−output option could
     cause it to store files somewhere git‐annex won’t find
     them. Avoid setting here or in the youtube−dl config
     file any options that cause youtube−dl to download more
     than one file, or to store the file anywhere other than
     the current working directory.

     Options to pass to aria2c when using it to download a

     HTTP headers to send when downloading from the web.
     Multiple lines of this option can be set, one per

     If set, the command is run and each line of its output
     is used as a HTTP header. This overrides
     List of URL schemes that git‐annex is allowed to
     download content from.  The default is "http https

     Think very carefully before changing this; there are
     security implications. For example, if it’s changed to
     allow "file" URLs, then anyone who can get a commit
     into your git‐annex repository could git‐annex addurl a
     pointer to a private file located outside that
     repository, possibly causing it to be copied into your
     repository and transferred on to other remotes,
     exposing its content.

     Some special remotes support their own domain−specific
     URL schemes; those are not affected by this
     configuration setting.

     By default, git‐annex only makes connections to public
     IP addresses; it will refuse to use HTTP and other
     servers on localhost or on a private network.

     This setting can override that behavior, allowing
     access to particular IP addresses that would normally
     be blocked. For example " ::1" allows access
     to localhost (both IPV4 and IPV6).  To allow access to
     all IP addresses, use "all"

     Think very carefully before changing this; there are
     security implications. Anyone who can get a commit into
     your git‐annex repository could git annex addurl an url
     on a private server, possibly causing it to be
     downloaded into your repository and transferred to
     other remotes, exposing its content.

     Note that, since the interfaces of curl and youtube−dl
     do not allow these IP address restrictions to be
     enforced, curl and youtube−dl will never be used unless−ip−addresses=all.

     To allow accessing local or private IP addresses on
     only specific ports, use the syntax "[addr]:port". For
     example, "[]:80 []:443 [::1]:80
     [::1]:443" allows localhost on the http ports only.−http−addresses
     Old name for−ip−addresses.  If
     set, this is treated the same as having−ip−addresses set.−unverified−downloads
     For security reasons, git‐annex refuses to download
     content from most special remotes when it cannot check
     a hash to verify that the correct content was
     downloaded. This particularly impacts downloading the
     content of URL or WORM keys, which lack hashes.

     The best way to avoid problems due to this is to
     migrate files away from such keys, before their content
     reaches a special remote.  See git‐annex−migrate(1).

     When the content is only available from a special
     remote, you can use this configuration to force git‐
     annex to download it.  But you do so at your own risk,
     and it’s very important you read and understand the
     information below first!

     Downloading unverified content from encrypted special
     remotes is prevented, because the special remote could


     send some other encrypted content than what you expect,
     causing git‐annex to decrypt data that you never
     checked into git‐annex, and risking exposing the
     decrypted data to any non−encrypted remotes you send
     content to.

     Downloading unverified content from (non−encrypted)
     external special remotes is prevented, because they
     could follow http redirects to web servers on localhost
     or on a private network, or in some cases to a file:///

     If you decide to bypass this security check, the best
     thing to do is to only set it temporarily while running
     the command that gets the file.  The value to set the
     config to is "ACKTHPPT".  For example:

      git −c−unverified−downloads=ACKTHPPT
     annex get myfile

     It would be a good idea to check that it downloaded the
     file you expected, too.

     Per−remote configuration of−unverified−downloads.


     Makes the watch and assistant commands delay for the
     specified number of seconds before adding a newly
     created file to the annex. Normally this is not needed,
     because they already wait for all writers of the file
     to close it.

     Controls what the assistant does about unused file
     contents that are stored in the repository.

     The default is false, which causes all old and unused
     file contents to be retained, unless the assistant is
     able to move them to some other repository (such as a
     backup repository).

     Can be set to a time specification, like "7d" or "1m",
     and then file contents that have been known to be
     unused for a week or a month will be deleted.


     When set to false, prevents the webapp from reminding
     you when using repositories that lack consistency

     When set to ask (the default), the webapp will check
     for new versions and prompt if they should be upgraded
     to. When set to true, automatically upgrades without
     prompting (on some supported platforms). When set to
     false, disables any upgrade checking.

     Note that upgrade checking is only done when git‐annex
     is installed from one of the prebuilt images from its
     website. This does not bypass e.g., a Linux
     distribution’s own upgrade handling code.

     This setting also controls whether to restart the git‐
     annex assistant when the git‐annex binary is detected
     to have changed. That is useful no matter how you
     installed git‐annex.

     Set to false to prevent the git‐annex assistant and
     git‐annex sync from automatically committing changes to
     files in the repository.

     To configure the behavior in all clones of the
     repository, this can be set in git‐annex−config(1).

     Set to false to prevent the git‐annex assistant from
     scanning the repository for new and changed files on
     startup. This will prevent it from noticing changes
     that were made while it was not running, but can be a
     useful performance tweak for a large repository.

     Configures which address the webapp listens on. The
     default is localhost.  Can be either an IP address, or
     a hostname that resolves to the desired address.

The key−value 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 SHA256E backend for ogg files:


      * annex.backend=WORM
 *.ogg annex.backend=SHA256E

     There is a annex.largefiles attribute, which is used to
configure which files are large enough to be added to the
annex. Since attributes cannot contain spaces, it is
difficult to use for more complex annex.largefiles settings.
Setting annex.largefiles in git‐annex−config(1) is an easier
way to configure it across all clones of the repository.
See git‐annex−matching−expression(1) for details on the

     The numcopies setting can also be configured on a
per−file−type basis via the annex.numcopies attribute in
.gitattributes files. This overrides other numcopies
settings.  For example, this makes two copies be needed for
wav files and 3 copies for flac files:

      *.wav annex.numcopies=2
 *.flac annex.numcopies=3

     Note that setting numcopies to 0 is very unsafe.

     These settings are honored by git‐annex whenever it’s
operating on a matching file. However, when using −−all,
−−unused, or −−key to specify keys to operate on, git‐annex
is operating on keys and not files, so will not honor the
settings from .gitattributes. For this reason, the git annex
numcopies command is useful to configure a global default
for numcopies.

     Also note that when using views, only the toplevel
.gitattributes file is preserved in the view, so other
settings in other files won’t have any effect.

git‐annex, when called as a git subcommand, may return exit
codes 0 or 1 for success or failures, or, more rarely, 127
or 128 for certain very specific failures.  git‐annex itself
should return 0 on success and 1 on failure, unless the
−−time−limit=time option is hit, in which case it returns
with exit code 101.

These environment variables are used by git‐annex when set:

     Handled the same as they are by git, see git(1)

     Handled similarly to the same as described in git(1).
     The one difference is that git‐annex will sometimes


     pass an additional "−n" parameter to these, as the
     first parameter, to prevent ssh from reading from
     stdin. Since that can break existing uses of these
     environment variables that don’t expect the extra
     parameter, you will need to set GIT_ANNEX_USE_GIT_SSH=1
     to make git‐annex support these.

     Note that setting either of these environment variables
     prevents git‐annex from automatically enabling ssh
     connection caching (see annex.sshcaching), so it will
     slow down some operations with remotes over ssh. It’s
     up to you to enable ssh connection caching if you need
     it; see ssh’s documentation.

     Also, annex.ssh−options and
     remote.<name>.annex−ssh−options won’t have any effect
     when these envionment variables are set.

     Usually it’s better to configure any desired options
     through your ~/.ssh/config file, or by setting

     Normally git‐annex timestamps lines in the log files
     committed to the git‐annex branch. Setting this
     environment variable to a number will make git‐annex
     use that rather than the current number of seconds
     since the UNIX epoch. Note that decimal seconds are

     This is only provided for advanced users who either
     have a better way to tell which commit is current than
     the local clock, or who need to avoid embedding
     timestamps for policy reasons. Misuse of this
     environment variable can confuse git‐annex’s
     book−keeping, sometimes in ways that git annex fsck is
     unable to repair.

Some special remotes use additional environment variables
     for authentication etc. For example, AWS_ACCESS_KEY_ID
     and GIT_ANNEX_P2P_AUTHTOKEN. See special remote

These files are used by git‐annex:

     .git/annex/objects/ in your git repository contains the
annexed file contents that are currently available. Annexed
files in your git repository symlink to that content.

     .git/annex/ in your git repository contains other
run−time information used by git‐annex.


     ~/.config/git‐annex/autostart is a list of git
repositories to start the git‐annex assistant in.

     .git/hooks/pre−commit−annex in your git repository will
be run whenever a commit is made to the HEAD branch, either
by git commit, git‐annex sync, or the git‐annex assistant.

     .git/hooks/post−update−annex in your git repository
will be run whenever the git‐annex branch is updated. You
can make this hook run git update−server−info when
publishing a git‐annex repository by http.

More git‐annex documentation is available on its web site,

     If git‐annex is installed from a package, a copy of its
documentation should be included, in, for example,

Joey Hess <>