git-annex-initremote(1)

💅 git-annex-initremote — the "make a new special (non-git) remote" moment

Okay bestie, so you know how git-annex has regular git remotes, right? This is the other kind. git-annex-initremote from the git-annex General Commands Manual creates a special (non-git) remote and honestly it's giving main character energy 🎀

---

✨ SYNOPSIS ✨

git annex initremote name type=value [param=value ...]

🌸 DESCRIPTION 🌸

It creates a brand new special remote and adds it to .git/config. That's the whole vibe. 🫶

Here's the iconic example — an Amazon S3 remote:

git annex initremote mys3 type=S3 encryption=hybrid
keyid=me@example.com datacenter=EU

git-annex supports so many different types of special remotes, no cap. For the full list and the details, go look at <https://git-annex.branchable.com/special_remotes/> 👑

The remote's configuration is literally specified by the parameters you pass to this command. Different types of special remotes need different configuration values, so pls consult the documentation of your special remote for the deets. The command will prompt you for any required parameters you leave out (it's so considerate 😭), and you can also pass --whatelse to see additional parameters.

A few parameters that are supported by all special remotes are documented in the next section below, iykyk.

Once a special remote has been initialized once with this command, other clones of the repository can also be set up to access it using git annex enableremote. Teamwork, bestie. ✨

⚠️ The name you provide for the remote can't be one that's been used for any other special remote before — because git annex enableremote uses the name to identify which special remote to enable. So the name is the whole identity, fr fr. If some old special remote that's no longer used has taken the name you want to reuse, you might want to use git annex renameremote to free it up. 💅

---

🔥 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. Slay.
• --whatelse / -w — describes additional configuration parameters that you could specify. Like, for example, if you know you want an S3 remote but you forgot how to configure it:

git annex initremote mys3 type=S3 --whatelse

And for a machine-readable list of the parameters, use this with --json. 🧚

• --fast — when initializing a remote that uses encryption, a cryptographic key is created. This requires sufficient entropy. If initremote seems to hang or take a long time while generating the key, you may want to Ctrl+c it and re-run with --fast, which causes it to use a lower-quality source of randomness. (Ie, /dev/urandom instead of /dev/random) 🍓
• --sameas=remote` — use this when the new special remote uses the same underlying storage as some other remote. This will result in the new special remote having the same uuid as the specified remote, and either can be used to access the same content. The remote can be the name of a git remote, or the description or uuid of any git-annex repository.

When using this option, the new remote inherits the encryption settings of the existing remote, so you should not specify any encryption parameters. No other configuration is inherited from the existing remote.

This will only work if both remotes use the underlying storage in compatible ways. See this page for information about known compatabilities: <http://git-annex.branchable.com/tips/multiple_remotes_accessing_the_same_data_store/>

• --private — avoid recording information about the special remote in the git-annex branch. The special remote will only be usable from the repository where it was created. 🙈

When used in combination with --sameas=foo, the configuration of the new special remote is kept private. But when files are sent to the new special remote, it will be public that they are present in remote "foo", unless it is also private.

• --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. Standard bestie behaviour. 💜

---

🦋 COMMON CONFIGURATION PARAMETERS 🦋

🔐 encryption

Almost all special remotes support encryption. You will need to specify what encryption, if any, to use.

• If you do not want any encryption, use encryption=none
• To encrypt to a GPG key, use encryption=hybrid keyid=$keyid ... and fill in the GPG key id (or an email address associated with a GPG key).

For details about this and other encryption settings, see <https://git-annex.branchable.com/encryption/> or --whatelse. ✨

⭐ autoenable

To avoid git annex enableremote needing to be run, you can pass "autoenable=true". Then when git-annex is run in a new clone, it 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. Lowkey effortless. 💅

💸 cost

Specify this to override the default cost of the special remote. This configuration can be overridden by the local git config, eg remote.name.annex-cost.

🆔 uuid

Normally, git-annex initremote generates a new UUID for the new special remote. If you want to, you can specify a UUID for it to use, by passing a uuid=whatever parameter. This can be useful in some unusual situations. But if in doubt, don't do this. 😭

💀 Real talk: that's a "you probably don't need it" situation, not a "let's get creative" situation.

---

🌈 SEE ALSO 🌈

• git-annex(1)
• git-annex-enableremote(1)
• git-annex-configremote(1)
• git-annex-renameremote(1)
• git-annex-disableremote(1)

---

👑 AUTHOR 👑

Joey Hess <id@joeyh.name> — the icon who made all of this.

---

Okay that's the whole page, bestie! This is git-annex-initremote(1) straight out of the git-annex General Commands Manual — go forth and initialize your special remotes. Periodt. 💖✨🎀