git-annex/ git-annex-drop

# NAME

git-annex drop - remove content of files from repository

# SYNOPSIS

git annex drop `[path ...]`

# DESCRIPTION

Drops the content of annexed files from this repository, when possible.

git-annex will refuse to drop content if it cannot verify it is safe to do so. Usually this involves verifying that the content is stored in some other repository.

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).

With no parameters, tries to drop all annexed files in the current directory. Paths of files or directories to drop can be specified.

# EXAMPLES

    # 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

# 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.

- `--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)

- `--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.

- `--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.

- `--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.

- `--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.

- `--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.

- `--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.

- `--json`

  Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object.

- `--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

git-annex(1)

git-annex-get(1)

git-annex-move(1)

git-annex-copy(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

comment 9

@yarikoptic --in --copies etc are documented in git-annex-matching-options which this page does link to.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 8

might be also worth referencing `find` as the ultimate source for options used by `drop` but not listed here, such as `--in`, `--copies` etc.

On behalf of struggling users Cheers

Comment by yarikoptic — Tue Jul 22 18:11:47 2025
re: drop everything but subdirectory

> Is there a way to drop everything except files under a given path in the repository?

You can use something like `git annex drop --exclude='subdir/*'`. See `man git-annex-matching-options`.

Comment by kyle — Tue Jul 22 18:11:47 2025
comment 6

Is there a way to drop everything except files under a given path in the repository? If not, it would be good to add this option. It should also not drop a file if it is outside the path but is pointed to by a relative symlink under the path.

Comment by https://me.yahoo.com/a/iOGTltEpmOTQ.xZ99NFP5c7Zdcc-#6a7ba — Tue Jul 22 18:11:47 2025
comment 5

@liori, see copies for how git-annex assures safety when dropping content.

Comment by joey — Tue Jul 22 18:11:47 2025
The meaning of "safe"
What does "safe" mean? Does `drop` just check if there are enough copies in other repositories in its local cache, does it contact remote repositories to check its own cache, or maybe even checks if the physical file in the remote repository has the right checksum?
Comment by https://launchpad.net/~liori — Tue Jul 22 18:11:47 2025
RE: choosing remotes and annex-cost-command

Finally got around to playing with this today figured i'd post an example for anyone looking fr this in the future. Please forgive the TCL code if that isn't your thing.

1. Adding the "cost command" to your remotes - Example here https://gist.github.com/zpeters/d288531db95aa69a495944a261d17b1c
2. The actual script being referenced is really basic. It's basically taking the name of the remote as an argument and depending on where i am it will give that remote a "high" or "low" cost. Code here https://gist.github.com/zpeters/89ba09289c89225ae5344e65c3562e6c
3. The cost script needs to know if I'm "home" or not. Here is an example of "whereami" https://gist.github.com/zpeters/cb8c2be53fd41b4d04a78fe81aaaea58

Comment by zpeters — Tue Jul 22 18:11:47 2025
comment 2

@zpeters, the order that remotes are accessed are ordered by cost.

You can configure the costs of remotes by setting remote.$name.annex-cost to eg 100 to make it be checked first or 300 to make it be checked later.

There's also a remote.$name.annex-cost-command that runs a command to get the cost. You could perhaps use that to detect which network you're on and alter the costs appropriately.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 11

@lh it builds for me and the man page looks ok. I suggest you file a bug report with the details about your problem.

Comment by joey — Tue Jul 22 18:11:47 2025
The man page export seems to be broken
When I rebuild the man pages on my system, this one has an error. Maybe there's a formatting issue?
Comment by lh — Tue Jul 22 18:11:47 2025
Choose which remote to lock when dropping

I might have a unique situation but i have a git annex repo that has multiple remotes for the same actual location. I have a server at home and when i'm "out in the world" i use it's external IP and when i'm at home i use it's internal IP. It appears that when i do an git annex drop on my laptop to compares and locks whichever remote is alphabetically first.

What i'm wondering is is there a way to tell git annex which remote i want to compare against? For example when i'm remote i want to do something like "git annex drop . --compare remoteServer"

Thank you!

Comment by zpeters — Tue Jul 22 18:11:47 2025
Comments on this page are closed.