f7fe71602c
Already supported --json, but not that. Also checked all other commands that only support --json, and the only other one that does transfers is fsck (--from), which it did not seem worth adding --json-progress to really.
206 lines
6.9 KiB
Markdown
206 lines
6.9 KiB
Markdown
# NAME
|
|
|
|
git-annex import - add a tree of files to the repository
|
|
|
|
# SYNOPSIS
|
|
|
|
git annex import --from remote branch[:subdir] | `[path ...]`
|
|
|
|
# DESCRIPTION
|
|
|
|
This command is a way to import a tree of files from elsewhere into your
|
|
git-annex repository. It can import files from a git-annex special remote,
|
|
or from a directory.
|
|
|
|
# IMPORTING FROM A SPECIAL REMOTE
|
|
|
|
Importing from a special remote first downloads all new content from it,
|
|
and then constructs a git commit that reflects files that have changed on
|
|
the special remote since the last time git-annex looked at it. Merging that
|
|
commit into your repository will update it to reflect changes made on the
|
|
special remote.
|
|
|
|
This way, something can be using the special remote for file storage,
|
|
adding files, modifying files, and deleting files, and you can track those
|
|
changes using git-annex.
|
|
|
|
You can combine using `git annex import` to fetch changes from a special
|
|
remote with `git annex export` to send your local changes to the special
|
|
remote.
|
|
|
|
You can only import from special remotes that were configured with
|
|
`importtree=yes` when set up with [[git-annex-initremote]](1). Only some
|
|
kinds of special remotes will let you configure them this way. A perhaps
|
|
non-exhastive list is the directory, s3, and adb special remotes.
|
|
|
|
To import from a special remote, you must specify the name of a branch.
|
|
A corresponding remote tracking branch will be updated by `git annex
|
|
import`. After that point, it's the same as if you had run a `git fetch`
|
|
from a regular git remote; you can merge the changes into your
|
|
currently checked out branch.
|
|
|
|
For example:
|
|
|
|
git annex import master --from myremote
|
|
git annex merge myremote/master
|
|
|
|
You could just as well use `git merge myremote/master` as the second step,
|
|
but using `git-annex merge` avoids a couple of gotchas. When using adjusted
|
|
branches, it adjusts the branch before merging from it. And it avoids
|
|
the merge failing on the first merge from an import due to unrelated
|
|
histories.
|
|
|
|
If you do use `git merge`, you can pass `--allow-unrelated-histories` the
|
|
first time you `git merge` from an import. Think of this as the remote
|
|
being a separate git repository with its own files. If you first
|
|
`git annex export` files to a remote, and then `git annex import` from it,
|
|
you won't need that option.
|
|
|
|
You can import into a subdirectory, using the "branch:subdir" syntax. For
|
|
example, if "camera" is a special remote that accesses a camera, and you
|
|
want to import those into the photos directory, rather than to the root of
|
|
your repository:
|
|
|
|
git annex import master:photos --from camera
|
|
git merge camera/master
|
|
|
|
The `git annex sync --content` command (and the git-annex assistant)
|
|
can also be used to import from a special remote.
|
|
To do this, you need to configure "remote.<name>.annex-tracking-branch"
|
|
to tell it what branch to track. For example:
|
|
|
|
git config remote.myremote.annex-tracking-branch master
|
|
git annex sync --content
|
|
|
|
If a preferred content expression is configured for the special remote,
|
|
it will be honored when importing from it. Files that are not preferred
|
|
content of the remote will not be imported from it, but will be left on the
|
|
remote.
|
|
|
|
However, preferred content expressions that relate to the key
|
|
can't be matched when importing, because the content of the file is not
|
|
known. Importing will fail when such a preferred content expression is
|
|
set. This includes expressions containing "copies=", "metadata=", and other
|
|
things that depend on the key. Preferred content expressions containing
|
|
"include=", "exclude=" "smallerthan=", "largerthan=" will work.
|
|
|
|
# IMPORTING FROM A DIRECTORY
|
|
|
|
When run with a path, `git annex import` moves files from somewhere outside
|
|
the git working copy, and adds them to the annex.
|
|
|
|
This is a legacy interface. It is still supported, but please consider
|
|
switching to importing from a directory special remote instead, using the
|
|
interface documented above.
|
|
|
|
Individual files to import can be specified. If a directory is specified,
|
|
the entire directory is imported.
|
|
|
|
git annex import /media/camera/DCIM/*
|
|
|
|
When importing files, there's a possibility of importing a duplicate
|
|
of a file that is already known to git-annex -- its content is either
|
|
present in the local repository already, or git-annex knows of another
|
|
repository that contains it, or it was present in the annex before but has
|
|
been removed now.
|
|
|
|
By default, importing a duplicate of a known file will result in
|
|
a new filename being added to the repository, so the duplicate file
|
|
is present in the repository twice. (With all checksumming backends,
|
|
including the default SHA256E, only one copy of the data will be stored.)
|
|
|
|
Several options can be used to adjust handling of duplicate files, see
|
|
`--duplicate`, `--deduplicate`, `--skip-duplicates`, `--clean-duplicates`,
|
|
and `--reinject-duplicates` documentation below.
|
|
|
|
# OPTIONS FOR IMPORTING FROM A DIRECTORY
|
|
|
|
* `--duplicate`
|
|
|
|
Do not delete files from the import location.
|
|
|
|
Running with this option repeatedly can import the same files into
|
|
different git repositories, or branches, or different locations in a git
|
|
repository.
|
|
|
|
* `--deduplicate`
|
|
|
|
Only import files that are not duplicates;
|
|
duplicate files will be deleted from the import location.
|
|
|
|
* `--skip-duplicates`
|
|
|
|
Only import files that are not duplicates. Avoids deleting any
|
|
files from the import location.
|
|
|
|
* `--clean-duplicates`
|
|
|
|
Does not import any files, but any files found in the import location
|
|
that are duplicates are deleted.
|
|
|
|
* `--reinject-duplicates`
|
|
|
|
Imports files that are not duplicates. Files that are duplicates have
|
|
their content reinjected into the annex (similar to
|
|
[[git-annex-reinject]](1)).
|
|
|
|
* `--force`
|
|
|
|
Allow existing files to be overwritten by newly imported files.
|
|
|
|
Also, causes .gitignore to not take effect when adding files.
|
|
|
|
* file matching options
|
|
|
|
Many of the [[git-annex-matching-options]](1)
|
|
can be used to specify files to import.
|
|
|
|
git annex import /dir --include='*.png'
|
|
|
|
## COMMON OPTIONS
|
|
|
|
* `--jobs=N` `-JN`
|
|
|
|
Imports multiple files in parallel. This may be faster.
|
|
For example: `-J4`
|
|
|
|
Setting this to "cpus" will run one job per CPU core.
|
|
|
|
* `--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.
|
|
|
|
# CAVEATS
|
|
|
|
Note that using `--deduplicate` or `--clean-duplicates` with the WORM
|
|
backend does not look at file content, but filename and mtime.
|
|
|
|
If annex.largefiles is configured, and does not match a file, `git annex
|
|
import` will add the non-large file directly to the git repository,
|
|
instead of to the annex.
|
|
|
|
# SEE ALSO
|
|
|
|
[[git-annex]](1)
|
|
|
|
[[git-annex-add]](1)
|
|
|
|
[[git-annex-export]](1)
|
|
|
|
[[git-annex-preferred-content]](1)
|
|
|
|
# AUTHOR
|
|
|
|
Joey Hess <id@joeyh.name>
|
|
|
|
Warning: Automatically converted into a man page by mdwn2man. Edit with care.
|