git-annex-whereis(1)

✨ git-annex-whereis ✨

okay bestie, this is a page from the git-annex manual set — it's git-annex-whereis, and it's genuinely one of the most useful little commands in the whole toolbox 💖

🌸 NAME 🌸

git-annex-whereis — the command that literally tells you which repositories are holding your file content 🎀

🦋 SYNOPSIS 🦋

git annex whereis [path ...]

💅 DESCRIPTION 💅

So here's the vibe: whereis shows you info about where the contents of your files actually live. Not the pointer files — the actual content. Iconic behaviour, no cap 👑

For example:

# git annex whereis
whereis my_cool_big_file (1 copy)
     0c443de8-e644-11df-acbf-f7cd7ca6210d  -- laptop
whereis other_file (3 copies)
     0c443de8-e644-11df-acbf-f7cd7ca6210d  -- laptop
     62b39bbe-4149-11e0-af01-bb89245a1e61  -- usb drive [here]
     7570b02e-15e9-11e0-adf0-9f3f94cb2eaa  -- backup drive

see how it counts the copies and then lists each repo by uuid with a cute lil name next to it? [here] means that one's you, main character energy 🫶

⚠️ okay important thing, ngl: this command does not contact remotes to check whether they actually still have the content. it only reports on the last information that was received from remotes. so it's a vibe check from memory, not a live verification 💀

---

✨ OPTIONS ✨

• matching options — you can absolutely use the git-annex-matching-options(1) to control what it acts on. filter away 🌈
• --key=keyname — show where one specific git-annex key is located. very "i know exactly what i'm looking for" of you 🔍
• --all, -A — show whereis info for all known keys. all of them. every single one 💫

(except for keys that have been marked as dead — those get skipped, see git-annex-dead(1). rip to them 🪦)

• --branch=ref — show whereis info for files in the branch or treeish you specify 🌿
• --unused — show whereis info for the files that were found by the last run of git-annex unused. leftovers have lore too 🍓
• --failed — operate on files that have recently failed to be transferred. the flops, we still love them 😭
• --batch — turns on batch mode: a file is read in a line from stdin, its info gets displayed, and then it repeats. over and over, little machine go brrr ⭐

note that if the file isn't an annexed file, or it doesn't match the matching options you specified, an empty line gets output instead. not nothing — an empty line, specifically 🙈

• --batch-keys — like --batch, but the lines read from stdin are parsed as keys instead of files 🔑
• -z — makes batch input be delimited by nulls instead of the usual newlines. null-separated, very edgy, very safe-for-weird-filenames 🦋
• --json — enables JSON output. it's meant to be parsed by programs that use git-annex, and each line of output is a JSON object 🤖
• --json-error-messages — messages that would normally go to standard error get included in the JSON instead. nothing escapes the JSON, everything is contained ✨
• --format=value — custom output formatting, aka make it look however you want 💅

the value is a format string, in which '${var}' gets expanded to the value of a variable. to right-justify a variable with whitespace, use '${var;width}' ; to left-justify a variable, use '${var;-width}' ; to escape unusual characters (including control characters) in a variable, use '${escaped_var}'

these variables are available for use in formats: file, key, uuid, url, backend, bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for the mtime field of a WORM key).

also, '\n' is a newline, '\000' is a NULL, etc.

when the format contains the uuid variable, it gets expanded in turn for each repository that contains the file content. for example, with --format="${file} ${uuid}\n", output will look like:

 foo 00000000-0000-0000-0000-000000000001
 foo a7f7ddd0-9a08-11ea-ab66-8358e4209d30
 bar a7f7ddd0-9a08-11ea-ab66-8358e4209d30

the same applies when the url variable is used and a file has multiple recorded urls. one line each, she contains multitudes 🌸

also the git-annex-common-options(1) can be used. free extra options, we love a bundle 🎁

---

🔥 SEE ALSO 🔥

• git-annex(1)
• git-annex-find(1)
• git-annex-list(1)

👑 AUTHOR 👑

Joey Hess <id@joeyh.name> — thank you king, the whole annex is your roman empire 🫶

---

and that's the whole page bestie! this one's the git-annex-whereis(1) page from the git-annex manual set, and it signs off with that classic git-annex-whereis(1) footer tag. go find your files, they're out there living their lives 💖✨🎀