git-annex-unused(1)

✨ git-annex-unused — look for unused file content ✨

ok so bestie, this is a page from the General Commands Manual, and it's literally called git-annex-unused. let's get into it 💅

---

🌸 NAME 🌸

git-annex-unused — look for unused file content

---

🦋 SYNOPSIS 🦋

git annex unused

---

💖 DESCRIPTION 💖

okay so here's the vibe: this command goes through your annex and checks for data that doesn't correspond to any files present in any tag or branch, or in the git index. basically it's like "who are you?? do you belong to anybody??" 🕵️♀️ and then it prints a numbered list of all that data. it's giving detective energy fr fr.

and then — this is the slay part — after you run this command, you can use the --unused option with a bunch of other git-annex commands to operate on all the unused data that was found. so this is like the setup, and --unused is the payoff. iconic behavior.

for example, to move all unused data to origin:

git annex unused; git annex move --unused --to origin

look at that. two commands, one semicolon, one beautiful cleanup. no cap. 🔥

---

✨ OPTIONS ✨

• --fast — only show unused temp and bad files. that's it, that's the whole thing. quick lil peek, no full sweep 🏃♀️
• --from=repository — check for unused data that is located in a repository. the repository should be specified using the name of a configured remote, or the UUID or description of a repository. so like, you can point at a specific place and be like "check there" 🎯
• --used-refspec=+ref:-ref — bestie listen. by default, any data that the git index uses, or that any refs in the git repository point to, is considered to be used. but if you only want to use some refs, you can use this option to specify the ones to use. then data that is not in the specified refs (and not used by the index) will be considered unused. it's like deciding who's in the group chat and who's getting left on read 💀

see REFSPEC FORMAT below for details of the format of this setting. yes there's a whole section. it's right down there. go look. 👀

the git configuration annex.used-refspec can be used to configure this in a more permanent fashion. so like, set it and forget it, main character energy ✨

• --json — enable JSON output. this is intended to be parsed by programs that use git-annex. so if you're a script, this one's for you 🫶
• --json-error-messages — messages that would normally be output to standard error are included in the JSON instead. so the errors get tucked into the JSON too. very "no message left behind" of it 💖

also the git-annex-common-options(1) can be used. always available, always welcome 🌈

---

🎀 REFSPEC FORMAT 🎀

okay so the refspec format for --used-refspec and annex.used-refspec is a colon-separated list of additions and removals of refs. a somewhat contrived example:

+refs/heads/*:+HEAD^:+refs/tags/*:-refs/tags/old-tag:reflog

let's break down what that gorgeous string is doing:

this adds all refs/heads/ refs, as well as the previous version of HEAD. it also adds all tags, except for old-tag. and it adds all refs from the reflog.

the default behavior is equivilant to --used-refspec=+refs/*:+HEAD

(yes, "equivilant" — that's how it's spelled in the source. we don't fix, we preserve. 💅)

the refspec is processed by starting with an empty set of refs, and walking the list in order from left to right. so like, it's a journey, and order matters bestie 🚶♀️

each + using a glob is matched against all relevant refs (a subset of git show-ref) and all matching refs are added to the set. for example, "+refs/remotes/*" adds all remote refs. globs go crazy, we love to see it ✨

each + without a glob adds the literal value to the set. for example, "+HEAD^" adds "HEAD^". just takes it at face value, no questions asked 🫶

each - is matched against the set of refs accumulated so far. any refs with names that match are removed from the set. bye bestie 👋

"reflog" adds all the refs from the reflog. this will make past versions of files not be considered to be unused until the ref expires from the reflog (by default for 90 days). note that this may make git-annex unused take some time to complete, it if needs to check every ref from the reflog.

⚠️ heads up: that reflog one is lowkey a lot of work. it might be slow. the original even says "it if needs to check" — yes, the typo is real, and we are keeping it fr fr. 😭

---

🌈 SEE ALSO 🌈

• git-annex(1)
• git-annex-dropunused(1)
• git-annex-addunused(1)
• git-annex-whereused(1)
• git-annex-oldkeys(1)

go read those too, they're all part of the same little family 💜

---

👑 AUTHOR 👑

Joey Hess <id@joeyh.name>

---

okay that's the whole page bestie!! shoutout to the General Commands Manual for hosting this, and to git-annex-unused(1) — the page title that also shows up in the footer, because it's got main character energy and needs to be seen twice 💖✨ periodt.