git-annex-drop(1)

📦
version 10.20261026 · 5 versions
, in alpine 3.24, arch rolling

💅 git-annex-drop — drop it like it's hot (but safely, bestie)

okay so real talk: this is the git-annex-drop manual page, and it's about removing the content of annexed files from your repository — not the file itself, just the actual bytes. and she's ✨careful✨ about it, which honestly? icon behavior.

🌸 NAME 🌸

git-annex-drop — remove content of annexed files from repository

🎀 SYNOPSIS 🎀

git annex drop [path ...]

✨ DESCRIPTION ✨

So what does she do? She drops the content of annexed files from this repository, when possible. That "when possible" is doing so much work, and it's the whole point. 🫶

git-annex will straight up refuse to drop content if it cannot verify it is safe to do so. And what does "safe" mean? Usually it means verifying that the content is stored in some other repository. like, she's not gonna let you delete the last copy and then act surprised, no ma'am.

Also important: content that is required to be stored in the repository will not be dropped, even if enough copies exist elsewhere. see git-annex-required(1) for the deets.

With no parameters, she tries to drop all annexed files in the current directory. You can also pass paths of files or directories to drop, iykyk.

💖 EXAMPLES 💖

here's the vibe in action — one wins, one gets told no 🙈:

 # git annex drop *.jpeg
 drop photo1.jpg (checking origin...) ok
 drop photo2.jpg (unsafe)
   Could only verify the existence of 0 out of 1 necessary copies

   Rather than dropping this file, try using: git annex move

   (Use --force to override this check, or adjust numcopies.)
 failed
 drop photo3.jpg (checking origin...) ok

look at photo2.jpg fighting for its life. she said unsafe, she said rather than dropping this file, try using: git annex move, and honestly? iconic of her to warn you.

🔥 OPTIONS 🔥

  • --from=remote — Rather than dropping the content of files in the local repository, this option can specify a remote from which the files' contents should be removed. (so you're dropping over there instead of here, teleportation but make it deletion 💅)
  • --fast — When dropping from a remote, avoid doing anything when the remote is not believed to contain a file. Usually each file is attempted to be dropped from the remote. This can be faster, but might leave some files on the remote in some cases. (speed 🔥 at the cost of maybe leaving stuff behind — trade-offs, bestie)
  • --auto — Rather than trying to drop all specified files, drop only those that are not preferred content of the repository, and avoid trying to drop files when there are not enough other copies for the drop to be possible. See git-annex-preferred-content(1).

When dropping from a remote, this avoids doing anything when the remote is not belived to contain a file. (yes, belived — that's the spelling in the original, and I'm not gonna gaslight you about it 😭)

  • --force — Use this option with care! ⚠️ It bypasses safety checks, and forces git-annex to delete the content of the specified files, even from the last repository that is storing their content. Data loss can result from using this option. like, fr fr, this is the one that can actually ruin your day 💀
girlypop. please read the --force entry again. that's the whole entire warning. deleting the last copy = the content is GONE. no cap.
  • --all, -A — Rather than specifying a filename or path to drop, this option can be used to drop all available versions of all files.

This is the default behavior when running git annex drop in a bare repository.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings. 👀

  • --branch=ref — Drop files in the specified branch or treeish.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings. (same bypass energy, different flag 💫)

  • --unused — Drop files found by last run of git-annex unused.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings.

  • --failed — Drop files that have recently failed to be transferred.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings.

  • --key=keyname — Use this option to drop a specified key.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings.

  • matching options — The git-annex-matching-options(1) can be used to specify what to drop. (customize your target list, main character energy 🎯)
  • --jobs=N, -JN — Runs multiple drop jobs in parallel. This is particularly useful when git-annex has to contact remotes to check if it can drop files. For example: -J4

Setting this to "cpus" will run one job per CPU core. (go off, let the whole machine eat 🍽️)

  • --batch — Enables batch mode, in which lines containing names of files to drop are read from stdin.

As each specified file is processed, the usual output is displayed. If a file's content is not present, or it does not match specified matching options, or it is not an annexed file, a blank line is output in response instead.

  • --batch-keys — This is like --batch but the lines read from stdin are parsed as keys.

Note that this bypasses checking the .gitattributes annex.numcopies setting and required content settings.

  • -z — Makes the batch input be delimited by nulls instead of the usual newlines. (weird little separator but she's valid 🌈)
  • --json — Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object. (machine-readable slay 🤖✨)
  • --json-error-messages — Messages that would normally be output to standard error are included in the JSON instead.

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

🦋 SEE ALSO 🦋

👑 AUTHOR 👑

Joey Hess <id@joeyh.name> — thank you for the lore, king 🫡

and that's the whole page, bestie! this documentation came to you via the General Commands Manual for git-annex-drop(1), source/version and date exactly as printed on the original footer: git-annex-drop(1), dated at the bottom of the General Commands Manual page. go forth and drop responsibly 💜🎀✨

📦 where this page comes from