git-annex-metadata(1)

💖 NAME 💖

git-annex-metadata — sets or gets metadata of a file ✨

---

🦋 SYNOPSIS 🦋

git annex metadata [path ...]

---

🌸 DESCRIPTION 🌸

okay so bestie, imagine this: the content of an annexed file can have literally any number of metadata fields attached to it, just to describe it 💅. and each one of those fields can have any number of values too. it's giving infinite vibes.

this command does two jobs: it can set metadata, or it can show you the metadata that's currently set. main character energy fr.

• when you run it with no -s or -t parameters at all, it just displays the current metadata. simple as that. ✨

every metadata field has its own little sidekick called field-lastchanged, which holds the date that field was last changed. and unlike other metadata, you cannot directly modify this one with this command — it updates itself automatically. no cap, it's self-sufficient.

⚠️ big important note bestie: metadata is attached to the git-annex key that corresponds to the content of a file, not to a particular filename on a particular git branch. so all files with the same key share the same metadata, and that metadata lives in the git-annex branch. if a file gets modified, the metadata of the previous version will be copied over to the new key when git-annex adds the modified file. 🫶

---

🎀 OPTIONS 🎀

• -g field / --get field — get the value(s) of a single field. the values come out one per line with no other output, so it's perfect for using inside a script. slay. 🔥
• -s field=value / --set field=value — set a field's value, and remove any old values while you're at it. out with the old 💅
• -s field+=value / --set field+=value — add an additional value, preserving any old values. it's additive, it's generous, it's iconic 🎀
• -s field?=value / --set field?=value — set a value, but only if the field does not already have a value set. shy but respectful.
• -s field-=value / --set field-=value — remove a value from a field, leaving any other values that the field has set. bye bestie 👋
• -r field / --remove field — remove all current values of the field. no survivors.
• -t tag / --tag tag — set a tag. note that a tag is just a value of the "tag" field. that's it, that's the whole trick. iykyk.
• -u tag / --unset tag — unset a tag. ✨
• --remove-all — remove all metadata from the specified files.

here's the situation: when a file is modified and the new version is added, git-annex will copy over the metadata from the old version of the file. in situations where you don't want that copied metadata, this option is your girl 💖

• --force — by default, git annex metadata refuses to recursively set metadata throughout the files in a directory. this option enables such recursive setting. consent unlocked 🔓
• matching options — the git-annex-matching-options(1) can be used to control what to act on. 👑
• --all -A — specify instead of a file to get/set metadata on all known keys.
• --branch=ref — specify instead of a file to get/set metadata on all files in the specified branch or treeish.
• --unused — specify instead of a file to get/set metadata on files found by last run of git-annex unused.
• --key=keyname — specify instead of a file to get/set metadata of the specified key.
• --json — enable JSON output (and input). each line is a JSON object.

the format of the JSON objects changed in git-annex version 6.20160726. so keep that in mind, bestie.

example of the new format:

{"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true}

example of the old format, which lacks the inner fields object:

{"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}

• --json-error-messages — messages that would normally be output to standard error are included in the JSON instead. no stray text, all contained 🎀
• --batch — enables batch mode, which can be used to both get, store, and unset metadata for multiple files or keys.

batch currently only supports JSON input. so, you must enable --json along with --batch. both or nothing, periodt.

in batch mode, git-annex reads lines from stdin, which contain JSON objects. it replies to each input annexed file with an output JSON object. (but if the file is not an annexed file, an empty line will be output.)

the format of the JSON sent to git-annex can be the same as the JSON that it outputs. or, a simplified version. only the "file" (or "key") field is actually necessary. lowkey efficient.

for example, to get the current metadata of file foo:

{"file":"foo"}

to get the current metadata of the key k:

{"key":"k"}

any metadata fields included in the JSON object will be stored, replacing whatever values the fields had before. to unset a field, include it with an empty list of values. 🫶

to change the author of file foo to bar:

{"file":"foo","fields":{"author":["bar"]}}

to remove the author of file foo:

{"file":"foo","fields":{"author":[]}}

• also the git-annex-common-options(1) can be used. ✨

---

🌈 EXAMPLES 🌈

to set some tags on a file and also its author:

git annex metadata annexscreencast.ogv -t video -t screencast -s author+=Alice

---

💜 SEE ALSO 💜

• git-annex(1)
• git-annex-view(1)

---

👑 AUTHOR 👑

Joey Hess <id@joeyh.name>

---

and that's the whole page bestie!! this was git-annex-metadata(1) from the General Commands Manual, and the footer said git-annex-metadata(1) again because man pages love repeating themselves 💀 — anyway ily, go set some metadata, you're gonna ate 💅✨🌸