git-annex/ git-annex-add

# NAME

git-annex add - adds files to the git annex

# SYNOPSIS

git annex add `[path ...]`

# DESCRIPTION

Adds the specified files to the annex. If a directory is specified, acts on all files inside the directory and its subdirectories. If no path is specified, adds files from the current directory and below.

Files that are already checked into git and are unmodified, or that git has been configured to ignore will be silently skipped.

If annex.largefiles is configured (in git config, gitattributes, or git-annex config), and does not match a file, `git annex add` will behave the same as `git add` and add the non-large file directly to the git repository, instead of to the annex. (By default dotfiles and the contents of dotdirs) are assumed to not be large, and are added directly to git, but annex.dotfiles can be configured to annex those too.) See the git-annex manpage for documentation of these and other configuration settings.

By default, large files are added to the annex in locked form, which prevents further modification of their content until unlocked by git-annex-unlock(1). (This is not the case however when a repository is in a filesystem not supporting symlinks.) The annex.addunlocked git config (and git-annex config) can be used to change this behavior.

This command can also be used to add symbolic links, both symlinks to annexed content, and other symlinks.

# EXAMPLES

    # git annex add foo bar
    add foo ok
    add bar ok
    # git commit -m added

# OPTIONS

- `--no-check-gitignore`

  Add gitignored files.

- `--force-large`

  Treat all files as large files, ignoring annex.largefiles and annex.dotfiles configuration, and add to the annex.

- `--force-small`

  Treat all files as small files, ignoring annex.largefiles and annex.dotfiles and annex.addsmallfiles configuration, and add to git.

- `--backend`

  Specifies which key-value backend to use.

- file matching options

  Many of the git-annex-matching-options(1) can be used to specify files to add.

  For example: `--largerthan=1GB`

- `--jobs=N` `-JN`

  Adds multiple files in parallel. This may be faster. For example: `-J4`

  Setting this to "cpus" will run one job per CPU core.

- `--update` `-u`

  Like `git add --update`, this does not add new files, but any updates to tracked files will be added to the index.

- `--dry-run`

  Output what would be done for each file, but avoid making any changes.

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

  Include progress objects in JSON output.

- `--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 to add is read in a line from stdin, the file is added, and repeat.

  Note that if a file is skipped (due to not existing, being gitignored, already being in git, or doesn't meet the matching options), an empty line will be output instead of the normal output produced when adding a file.

- `-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-unlock(1)

git-annex-lock(1)

git-annex-undo(1)

git-annex-import(1)

git-annex-unannex(1)

git-annex-reinject(1)

# AUTHOR

Joey Hess id@joeyh.name

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

comment 7

@lh I don't feel this man page's comment section is the place to discuss this in detail. But suffice to say that even if add behaved the way you suggest, any other git-annex command can commit the accumulated changes to the git-annex branch at any time. So the change would not guarantee the behavior you hope for.

But, you can set annex.alwayscommit to false and run `git-annex merge` when you do want to commit changes to the git-annex branch.

Comment by joey — Wed Oct 29 14:05:27 2025
recording state in git

Why does git-annex-add record state in Git? This means if you change your mind before committing and unannex some files, those files are still left in the annex. Semantically, this makes git-annex-add feel more like a commit operation, which is confusing given the name.

Furthermore, to forcibly drop these files, you have to take the output `git annex whereused --unused --historical` and compare it against the output of `git annex unused` to get a list of files that don't show up anywhere in the history. This is rather cumbersome for dropping files you never committed.

Couldn't the `git-annex` branch use the index, like git itself, so unannexing wouldn't leave you with extraneous files?

I get the safety perspective, but I feel like that's what `git commit` (and a hypothetical `git annex commit`) should be for. The staging area is useful to verify you're actually committing what you want. I know I'm probably a decade late here, but I'd be interested to hear your thoughts, anyway. It seems weird to deviate from git here.

Comment by lh — Wed Oct 29 14:05:27 2025
comment 5

You use `git-annex add` when you have a file located inside your git-annex repository, which you want to check in.

You use `git-annex import` when you have some other thing storing files and you want git-annex to learn about the files stored there. Using git-annex import to move individual files to the repository and add them is not significantly different than mv+add and will eventually be deprecated.

Comment by joey — Wed Oct 29 14:05:27 2025
comment 4
But is there a difference to `git annex import`? What is the difference? Why would you use `git annex add` instead of `git annex import`?
Comment by AlbertZeyer — Wed Oct 29 14:05:27 2025
comment 3

The various configuration options are documented in the main git-annex manpage, at the bottom.

If it is a one-shot, just use `cp/mv` and `git annex add`. If you want to frequently import from that location, use directory special-remotes with importtree=yes.

Comment by Lukey — Wed Oct 29 14:05:27 2025
Adding external files

Let's assume I have some external files in my `~/Pictures` and I want to import them.

Should I use `git annex import ~/Pictures/BestPics2020` or `cp -r ~/Pictures/BestPics2020 .; git annex add BestPics2020`? Is there a difference? Which way would be recommended or preferred?

Comment by AlbertZeyer — Wed Oct 29 14:05:27 2025
annex.largefiles

Does annex.largefiles has some documentation? It would be nice to link to that on the doc of git-annex-add.

Esp, after reading this, I wonder about the default value of annex.largefiles. (I assume/hope it is disabled?)

Comment by AlbertZeyer — Wed Oct 29 14:05:27 2025
Comments on this page are closed.