Provided by: git-annex_10.20230626-1_amd64 bug

NAME

       git-annex-import - import files from a special remote

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 --allow-unrelated-histories myremote/master

       You  could  just  as well use git merge --allow-unrelated-histories 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.

       The  --allow-unrelated-histories  option  is  needed  for  at  least the first merge of an
       imported remote tracking branch, since the branch's history is  not  connected.  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.  In  contrast to importing from a special
       directory remote, imported files are **deleted from the given path**.

       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. Please note that the following instruction will **delete all  files
       from the source directory**.

        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.

       symbolic  links  in  the  directory  being  imported  are  skipped  to avoid accidentially
       importing things outside the directory that import was ran on. The directory  that  import
       is run on can, however inself be a symbolic link, and that symbolic link will be followed.

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.

       --backend
              Specifies which key-value backend to use for the imported files.

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

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

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)