git-annex/doc/git-annex-enableremote.mdwn

# 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.