git-annex-smudge(1)

💅 git-annex-smudge — the git filter driver glow-up

okay bestie, this is git-annex-smudge(1) from the General Commands Manual, and it's genuinely one of the most underrated little gremlins in the whole git-annex family. let's get into it 🫶

---

✨ NAME ✨

git-annex-smudge — it's a git filter driver for git-annex, periodt.

---

🌸 SYNOPSIS 🌸

git annex smudge [--clean] file

git annex smudge --update

like, two whole modes. one for a file, one for the whole vibe check.

---

🦋 DESCRIPTION 🦋

so the way this works: this command lets git-annex be used as a git filter driver, which means annexed files in the git repo can be unlocked instead of being symlinks 💅, and it also lets git add store files in the annex.

when you add a file with git add, the annex.largefiles config gets consulted to decide if that file should just be added to git as-is, or if its content is large enough that it needs git-annex. and the annex.gitaddtoannex setting overrides that — set it to false and git add will literally not add files to the annex. no cap.

however (and this is the plot twist 😭) if git-annex can tell that a file was annexed before, it'll still add it to the annex even when those configs would normally prevent it. two examples of this, bestie:

• adding a modified version of an annexed file
• moving an annexed file to a new filename and adding that

the git configuration to use this command as a filter driver is as follows. this is normally set up for you by git-annex init, so you should not need to configure it manually:

[filter "annex"]
        smudge = git-annex smudge %f
        clean = git-annex smudge --clean %f

to make git actually use that filter driver, it needs to be configured in the .gitattributes file or in .git/info/attributes. the latter is normally configured when a repository is initialized, with the following contents:

* filter=annex

here's the thing though: the smudge filter does not give git the content of annexed files, because that would be slow and triggers memory leaks in git 💀. instead, it just records which worktree files need to be updated, and then git annex smudge --update later updates the work tree to contain the content. that one is run by several git hooks, including post-checkout and post-merge. but — and this is the part where you have to be your own main character — a few git commands, notably git stash and git cherry-pick, do not run any hooks. so after using those commands you can manually run git annex smudge --update (or git-annex fix) to update the working tree. 🙈

⚠️ lowkey important: no hooks means no automatic update. if your worktree is looking dusty after a git stash or git cherry-pick, that's why, and you gotta run the update yourself.

---

👑 OPTIONS 👑

• the git-annex-common-options(1) can be used 💖

---

🌈 SEE ALSO 🌈

git-annex(1) git-annex-filter-process(1)

---

🎀 AUTHOR 🎀

Joey Hess <id@joeyh.name>

---

okay that's the whole page, bestie ✨ and if you made it to the end, you get the cute sign-off: this was git-annex-smudge(1) from the General Commands Manual — go forth, smudge responsibly, and remember to update that worktree 🌸💜