git-annex/ git-annex-enableremote

# NAME

git-annex enableremote - enables git-annex to use a remote

# SYNOPSIS

git annex enableremote `name|uuid|desc [param=value ...]`

# DESCRIPTION

Enables use of an existing remote in the current repository, that was set up earlier by `git annex initremote` run in another clone of the repository.

When enabling a remote, specify the same name used when originally setting up that remote with `git annex initremote`. Run `git annex enableremote` without any name to get a list of remote names. Or you can specify the uuid or description of the remote.

Some types of special remotes need parameters to be specified every time they are enabled. For example, the directory special remote requires a directory= parameter every time. The command will prompt for any required parameters you leave out.

This command can also be used to modify the configuration of an existing special remote, by specifying new values for parameters that are usually set when using initremote. (However, some settings such as the as the encryption scheme cannot be changed once a special remote has been created.)

The GPG keys that an encrypted special remote is encrypted with can be changed using the keyid+= and keyid-= parameters. These respectively add and remove keys from the list. However, note that removing a key does NOT necessarily prevent the key's owner from accessing data in the encrypted special remote (which is by design impossible, short of deleting the remote).

One use-case of keyid-= is to replace a revoked key with a new key:

    git annex enableremote mys3 keyid-=revokedkey keyid+=newkey

Also, note that for encrypted special remotes using plain public-key encryption (encryption=pubkey), adding or removing a key has NO effect on files that have already been copied to the remote. Hence using keyid+= and keyid-= with such remotes should be used with care, and make little sense except in cases like the revoked key example above.

If you get tired of manually enabling a special remote in each new clone, you can pass "autoenable=true". Then when git-annex-init(1) is run in a new clone, it will will attempt to enable the special remote. Of course, this works best when the special remote does not need anything special to be done to get it enabled.

(This command also can be used to enable a git remote that git-annex has found didn't work before and gave up on using, setting `remote.<name>.annex-ignore`.)

# OPTIONS

- `--with-url`

  This configures the remote with an "annex::" url, which allows git to push to and pull from it, using git-remote-annex.

- `--json`

  Enable JSON output. This is intended to be parsed by programs that use git-annex.

- `--json-error-messages`

  Messages that would normally be output to standard error are included in the JSON instead.

- Also, the git-annex-common-options(1) can be used.

# SEE ALSO

git-annex(1)

git-annex-initremote(1)

git-annex-configremote(1)

git-annex-renameremote(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

comment 3
Thanks much, did not think to use the 'describe' for that but that's very intuitive!
Comment by https://me.yahoo.com/a/80VlVB0Bx9TaNOXIj3OCQ8eimAtIOhqjUQ--#1e80e — Wed Oct 29 14:05:27 2025
Retrieving initremote parameters for new user

Is there a way to determine the parameters that an enableremote command must use, if one does not know it? The use case is as follows: * Dev 1 performs an `initremote annexed-media directory=/path/to/media ...` * Dev 1 syncs content * Dev 2 comes along (or Dev 1 comes along months later with a different machine) and clones the repo, but needs to know the directory=/path... in order to 'enableremote'. Is there any way to glean this information from the source repo itself?

The steps would be:

    dev1$ git clone git@gitserver:myproject.git && cd myproject
    dev1$ mkdir images && touch images/foo1.png
    dev1$ git annex initremote annexation.dir directory=/mnt/media/myproject.annex/ encrypted=false
    dev1$ git commit && git push && git annex sync --content

    dev2$ git clone git@gitserver:myproject.git && cd myproject
    dev2$ git annex whereis
    # shows something like ...
    #    whereis images/foo1.png (7 copies) ...
    #        38e67e39-7dfb-45e8-90fc-8c5d01aae0b4 -- annexation.dir
    dev2$ git annex enableremote annexation.dir directory=???

So how does the new developer know how to define the annexation.dir? Is there any way to extract from the repo itself? Or must this information be saved into the repo's documentation to avoid losing the reference?

Thanks!

Comment by https://me.yahoo.com/a/80VlVB0Bx9TaNOXIj3OCQ8eimAtIOhqjUQ--#1e80e — Wed Oct 29 14:05:27 2025
comment 2

@Sundar, good question.

`git annex enableremote` will always refuse to enable the remote if there's a missing parameter, and prompt for the parameter. Finding the right value is up to you. Most of the time, no additional parameters are needed, or the parameters are fairly self-explanatory, eg login passwords for remote services.

The difficulty with directory special remotes is that my /foo may not be the same as your /foo, so it can't reuse the directory= that was provided to initremote, and it's up to you to enter the right directory path.

I think this needs to come down to documentation in the repository. The description of the remote (set by `git annex describe` is a reasonable place to put that, unless you have somewhere better.

Comment by joey — Wed Oct 29 14:05:27 2025
Comments on this page are closed.