git-annex-unlock(1)

📦
version 10.20261026 · 4 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 git-annex-unlock(1) — bestie edition

okay so you found the git-annex-unlock page in the General Commands Manual and honestly? iconic choice. this is the one that unlocks files for modification. let's get into it 🫶

✨ NAME ✨

git-annex-unlock — unlock files for modification

🌸 SYNOPSIS 🌸

git annex unlock [path ...]

🦋 DESCRIPTION 🦋

so like, normally? the content of annexed files is protected from being changed. it's giving museum glass, look don't touch 💅. Unlocking an annexed file is what allows it to be modified. and if you specify no files at all, every annexed file in the current directory gets unlocked. the whole squad. periodt.

Now here's the tea ☕ — unlocking a file changes how it is stored in the git repository (it goes from a symlink to a pointer file), so this command will make a change that you can commit. like, it's a real change, not just a vibe.

But wait, don't panic: the content of an unlocked file is still stored in git-annex, not git. and when you commit modifications to the file, those modifications will also be stored in git-annex, with only the pointer file stored in git. so git stays skinny, git-annex holds the substance. main character energy, honestly. 👑

If you use git add to add a file to the annex, it will be added in unlocked form from the beginning. this unlocks (lol) a whole workflow where a file starts out unlocked, gets modified as necessary, and is locked once it reaches its final version. glow-up pipeline. ✨

⚠️ okay bestie listen up because this part is important: normally, unlocking a file requires a copy to be made of its content, so that its original content is preserved while the copy can be modified. it's a safety copy, it's not free.

To use less space, annex.thin can be set to true; this makes a hard link to the content be made instead of a copy. (Only when supported by the file system.) While this can save considerable disk space, any modification made to a file will cause the old version of the file to be lost from the local repository. so, enable annex.thin with care. fr fr. 🚨

🎀 EXAMPLES 🎀

 # git annex unlock disk-image
 # git commit -m "unlocked to allow VM to make changes as it runs"

 # git annex unlock photo.jpg
 # gimp photo.jpg
 # git commit photo.jpg -m "redeye removal"
 # gimp photo.jpg
 # git commit photo.jpg -m "fix oversaturation" # git annex lock
photo.jpg

look at that little photo.jpg workflow, she's doing the work. unlock, edit, commit, edit, commit, lock. 💖

💅 OPTIONS 💅

  • file matching options — the git-annex-matching-options(1) can be used to specify files to unlock. so you can be picky about which files get the treatment 🎯
  • --json — Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object. robots-only zone, no cap 🤖
  • --json-error-messages — Messages that would normally be output to standard error are included in the JSON instead. so your error messages get folded into the JSON too, nothing gets lost 💌

Also the git-annex-common-options(1) can be used. those ones always come to the party 🌈

🌟 SEE ALSO 🌟

(the lock one is literally the reverse move, go read it, they're a matched set 🫶)

👑 AUTHOR 👑

Joey Hess <id@joeyh.name>

and that's the whole page bestie, git-annex-unlock(1), out here doing the most for your file-modification needs 💜 go unlock something, commit it, and live your truth. slay. 🦋🌸

📦 where this page comes from