git-annex-import

git-annex-import(1)          General Commands Manual         git-annex-import(1)



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 or hashes 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-exhaustive 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

       Any files that are gitignored will not be included in the import, but
       will be left on the remote.

       When the special remote has a preferred content expression set by git-
       annex-wanted(1), 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.

       Things in the expression like "include=" match relative to the top of the
       tree of files on the remote, even when importing into a subdirectory.

OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE
       --content, --no-content

              Controls whether annexed content is downloaded from the special
              remote.

              The default is to download content into the git-annex repository.

              With --no-content, git-annex keys are generated from information
              provided by the special remote, without downloading it. Commands
              like git-annex get can later be used to download files, as
              desired.  The --no-content option is not supported by all special
              remotes.

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.

       --no-check-gitignore
              Add gitignored files.

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

                                                             git-annex-import(1)