git-remote-annex(1)

💖 git-remote-annex — like, the manual page, bestie 💖

okay so this is git-remote-annex(1), straight out of the General Commands Manual, and I'm gonna walk you through it like we're texting at 2am. it's giving niche but iconic. 🎀

---

✨ NAME ✨

git-remote-annex — a remote helper program that stores a git repository inside a git-annex special remote. no cap, that's the whole job. 🫶

---

🌸 SYNOPSIS 🌸

git fetch annex::uuid?param=value&param=value...

that's it. that's the shape of it. 💅

---

🦋 DESCRIPTION 🦋

so this is a git remote helper program. which means it lets git clone, pull and push from a git repository that lives inside a git-annex special remote — as long as the URL starts with annex::. literally that prefix is the whole vibe check. ✨

the special remote needs a remote.<name>.url configured to use this. good news tho: that gets set up automatically when you're git cloning from a special remote. no extra work, we love that. 😌

if you want git-annex-initremote(1) and git-annex-enableremote(1) to configure the url for you, just pass them the --with-url option. easy. 🎀

or — if you've already got an existing special remote and you wanna configure it with a shorthand URL — run:

git config remote.name.url annex::

once the URL is configured, you can just use git pull, git push, etc. with the special remote pretty much like any other git remote. 💖

⚠️ but bestie, check out CONFLICTING PUSHES below, because there are some situations where it behaves a little differently. not a red flag, just a heads up. 🚩

---

🌈 URL FORMAT 🌈

the URL starts with annex::. there are three forms of such URLs, and each one is its own lil main character:

👑 Complete URL

this one contains the UUID and all the configuration parameters of the special remote that were passed when you used git-annex initremote. it's the full package, no secrets. 💅

for example, to clone from a directory special remote:

git clone annex::358ff77e-0bc3-11ef-bc49-872e6695c0e3?type=directory&encryption=none&directory=/mnt/foo/

look at that UUID. iconic. 🔥

🎀 Shorthand URL

this makes it easy to configure an existing special remote with an URL, without having to come up with the complete URL yourself. we love a shortcut.

annex::

when you use this shorthand URL, the full URL will be displayed each time you git pull or push — whenever it's possible for git-annex to determine it.

(although, in some cases — like the directory special remote — some parameters may be left off of the displayed URL. so it's almost the whole thing. still cute.) 🙈

🧚 Web URL

this URL points at a file on the web, and that file contains the complete annex:: URL. it's like a URL that's holding another URL's hand. 🫶

annex::https://example.com/foo-repo

💀 not all special remotes can be accessed by such an URL, for security reasons. currently, this is limited to httpalso special remotes. periodt.

---

⚡ CONFLICTING PUSHES ⚡

like any git repository, a git repository stored on a special remote can have conflicting things pushed to it from different places. messy? a little. but it mostly works the same as any other git repository — for example, a push that overwrites other work will be prevented unless forced. git said "not on my watch." 💅

however — and this is the part you need to know — when conflicting pushes are being done at the same time, it is possible for one of the pushes to be overwritten by the other one. 😭

in that situation, the overwritten push will appear to have succeeded. but pulling later will show the true situation. so like... it lied to your face. 🙈

---

🔥 REPOSITORY FORMAT 🔥

the git repository is stored in the special remote using special annex objects with names starting with GITMANIFEST and GITBUNDLE. for details, see:

https://git-annex.branchable.com/internals/git-remote-annex/

pushes to a special remote are usually done incrementally. however, sometimes the whole git repository gets re-uploaded. that happens when:

• you force push a ref
• you delete a ref from the remote

it's also done when too many git bundles accumulate in the special remote — as configured by the remote.<name>.annex-max-git-bundles git config. 👑

📌 note that a re-upload of the repository does not delete old GITBUNDLE objects from it. which means refs pushed to the special remote can still be accessed even after deleting or overwriting them. they're just... still there. lurking. in a cute way. 💀

a push that deletes every ref from the special remote will delete all the accumulated GITBUNDLE objects. but of course, making such a push means that someone who clones from the special remote at that point in time will see an empty remote. so like, know what you're doing bestie. 😭

---

🌟 SEE ALSO 🌟

• gitremote-helpers(1)
• git-annex(1)
• git-annex-initremote(1)

---

💜 AUTHOR 💜

Joey Hess <id@joeyh.name> — an absolute legend, fr fr. 👑

---

and that's the whole page, bestie!! this was git-remote-annex(1) from the General Commands Manual, and yeah — the footer is just git-remote-annex(1) again, like a lil echo. go forth and clone. slay. ✨🎀💖