git-annex/ git-annex-find

# NAME

git-annex find - lists available files

# SYNOPSIS

git annex find `[path ...]`

# DESCRIPTION

Outputs a list of annexed files in the specified path. With no path, finds files in the current directory and its subdirectories.

# OPTIONS

- matching options

  The git-annex-matching-options(1) can be used to specify files to list.

  By default, the find command only lists annexed files whose content is currently present. Specifying any of the matching options will override this default behavior.

  To list all annexed files, present or not, specify `--anything`.

  To list annexed files whose content is not present, specify `--not --in=here`

- `--branch=ref`

  List files in the specified branch or treeish.

- `--print0`

  Output filenames terminated with nulls, for use with `xargs -0`

- `--format=value`

  Use custom output formatting.

  The value is a format string, in which '${var}' is 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, 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.

  The default output format is the same as `--format='${file}\\n'`, except when outputting to a terminal, control characters will be escaped.

- `--json`

  Output the list of files in JSON format.

  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.

- `--batch`

  Enables batch mode, in which a file is read in a line from stdin, its information displayed, and repeat.

  Note that if the file is not an annexed file, or is not present, or otherwise doesn't meet the matching options, an empty line will be output instead.

- `-z`

  Makes the `--batch` input be delimited by nulls instead of the usual newlines.

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

# SEE ALSO

git-annex(1)

git-annex-whereis(1)

git-annex-findkeys(1)

# AUTHOR

Joey Hess id@joeyh.name

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

"dry run" option
@Dan Related: wishlist: --dry-run option for all commands (but should probably move this thread to todo).
Comment by Ilya_Shlyakhter — Tue Jul 22 18:11:47 2025
find wanted on remote?

Is there a way to use find to figure out what is wanted (for getting or dropping) on a given remote? I want to be able to do this to anticipate the outbound consequences of a sync (I can anticipate the inbound consequences of a sync, modulo file availability on remotes, using `git annex find --wanted-get --not --in here`).

I could manually figure out the wanted expressions for an arbitrary remote (resolving any group assignments, etc) and then use that expression, but it'd be nice to be able to do something like `git annex find --wanted-get-at remotename --not --in remotename --in here` to figure out what things will get copied to the remote if I run `git annex sync --content`. I presume this logic is implemented somewhere since it gets used when doing `git annex sync --content`, and perhaps there's a way that I can do it using `git annex find` or other commands and I'm just not seeing how to do it.

Comment by Dan — Tue Jul 22 18:11:47 2025
Find (and other operations) over multiple repos

Sometimes I want to move files from one git annex repo to another. It would be really awesome if one could so something like:

    git annex find --in here --and --not --in-repo /path/to/OTHER-REPO

Just to make myself clear. I do not mean "other remote" (foreign instance of "same" repo). I actually mean different repos without common location tracking, no common branches, etc. The only concession I would make (since I think it's necessary) would be that the same backend has to be used in both repos.

This approach could also be relevant for other git annex commands, e.g.:

    git annex move file --to-repo /path/to/OTHER-REPO

Is there any way to do it? Or would this be a feature request worth to consider?

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