diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn index 0a55ea9d56..1d01f2b7cd 100644 --- a/doc/git-annex-export.mdwn +++ b/doc/git-annex-export.mdwn @@ -6,8 +6,6 @@ git-annex export - export content to a remote git annex export `treeish --to remote` -git annex export `--tracking treeish --to remote` - # DESCRIPTION Use this command to export a tree of files from a git-annex repository. @@ -45,6 +43,16 @@ paragraph do not apply. Note that dropping content from such a remote is not supported. See individual special remotes' documentation for details of how to enable such versioning. +The `git annex sync --content` command (and the git-annex assistant) +can also be used to export a branch to a special remote, +updating the special remote whenever the branch is changed. +To do this, you need to configure "remote..annex-tracking-branch" +to tell it what branch to track. +For example: + + git config remote.myremote.annex-tracking-branch master + git annex sync --content + # OPTIONS * `--to=remote` @@ -53,13 +61,9 @@ details of how to enable such versioning. * `--tracking` - This makes the export track changes that are committed to - the branch. `git annex sync --content` and the git-annex assistant - will update exports with commits made to the branch. - - This is a local configuration setting, similar to a git remote's tracking - branch. You'll need to run `git annex export --tracking` in each - repository you want the export to track. + This is a deprecated way to set "remote..annex-tracking-branch". + Instead of using this option, you should just set the git configuration + yourself. * `--fast` @@ -69,28 +73,24 @@ details of how to enable such versioning. # EXAMPLE - git annex initremote myexport type=directory directory=/mnt/myexport \ + git annex initremote myremote type=directory directory=/mnt/myremote \ exporttree=yes encryption=none - git annex export master --to myexport + git annex export master --to myremote -After that, /mnt/myexport will contain the same tree of files as the master +After that, /mnt/myremote will contain the same tree of files as the master branch does. git mv myfile subdir/myfile git commit -m renamed - git annex export master --to myexport + git annex export master --to myremote -That updates /mnt/myexport to reflect the renamed file. +That updates /mnt/myremote to reflect the renamed file. - git annex export master:subdir --to myexport + git annex export master:subdir --to myremote -That updates /mnt/myexport, to contain only the files in the "subdir" +That updates /mnt/myremote, to contain only the files in the "subdir" directory of the master branch. - git annex export --tracking master --to myexport - -That makes myexport track changes that are committed to the master branch. - # EXPORT CONFLICTS If two different git-annex repositories are both exporting different trees @@ -116,6 +116,8 @@ export`, it will detect the export conflict, and resolve it. [[git-annex-initremote]](1) +[[git-annex-import]](1) + [[git-annex-sync]](1) # HISTORY diff --git a/doc/git-annex-import.mdwn b/doc/git-annex-import.mdwn index ee9f36f014..2a10d03d0e 100644 --- a/doc/git-annex-import.mdwn +++ b/doc/git-annex-import.mdwn @@ -1,16 +1,71 @@ # NAME -git-annex import - move and add files from outside git working copy +git-annex import - add files from a directory or special remote # SYNOPSIS -git annex import `[path ...]` +git annex import `[path ...]` | git annex import branch[:subdir] --from remote # DESCRIPTION -Moves files from somewhere outside the git working copy, and adds them to -the annex. Individual files to import can be specified. -If a directory is specified, the entire directory is imported. +This command is a way to import files from elsewhere into your git-annex +repository. It can import files from a directory into your repository, +or it can import files from a git-annex special remote. + +## 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. + +This can only be used with 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. + +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 `git merge` the changes into your +currently checked out branch. + +For example: + + git annex import master --from myremote + git merge myremote/master + +It's also posible to limit the import to 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 + +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. + +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..annex-tracking-branch" +to tell it what branch to track. For example: + + git config remote.myremote.annex-tracking-branch master + git annex sync --content + +## 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. + +Individual files to import can be specified. If a directory is specified, +the entire directory is imported. git annex import /media/camera/DCIM/* @@ -25,9 +80,11 @@ 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. +Several options can be used to adjust handling of duplicate files, see +`--duplicate`, `--deduplicate`, `--skip-duplicates`, `--clean-duplicates`, +and `--reinject-duplicates` documentation below. -# OPTIONS +# OPTIONS FOR IMPORTING FROM A DIRECTORY * `--duplicate` @@ -71,6 +128,8 @@ Several options can be used to adjust handling of duplicate files. git annex import /dir --include='*.png' +## COMMON OPTIONS + * `--jobs=N` `-JN` Imports multiple files in parallel. This may be faster. diff --git a/doc/git-annex-sync.mdwn b/doc/git-annex-sync.mdwn index 9ac27b65e5..a61de8c6a7 100644 --- a/doc/git-annex-sync.mdwn +++ b/doc/git-annex-sync.mdwn @@ -82,9 +82,12 @@ by running "git annex sync" on the remote. This behavior can be overridden by configuring the preferred content of a repository. See [[git-annex-preferred-content]](1). - When a special remote is configured as an export and is tracking a branch, - the export will be updated to the current content of the branch. - See [[git-annex-export]](1). + When `remote..annex-tracking-branch` is configured for a special remote + and that branch is checked out, syncing will import changes from + the remote, merge them into the branch, and export any changes that have + been committed to the branch back to the remote. See + See [[git-annex-import]](1) and [[git-annex-export]](1) for details about + how importing and exporting work. * `--content-of=path` `-C path` diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 35854eba0e..acca797b2d 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -1266,13 +1266,23 @@ Here are all the supported configuration settings. in some edge cases, where it's likely the case than an object was downloaded incorrectly, or when needed for security. +* `remote..annex-tracking-branch` + + When set to eg, "master", this tells git-annex that you want the + special remote to track that branch. + + When set to eg, "master:subdir", the special remote tracks only + the subdirectory of that branch. + + `git-annex sync --content` and the git-annex assistant will + import changes from the remote and merge them into the + annex-tracking-branch. They also export changes made to the branch to the + remote. + * `remote..annex-export-tracking` - When set to a branch name or other treeish, this makes what's exported - to the special remote track changes to the branch. See - [[git-annex-export]](1). `git-annex sync --content` and the - git-annex assistant update exports when changes have been - committed to the tracking branch. + Deprecated name for `remote..annex-tracking-branch`. Will still be used + if it's configured and `remote..annex-tracking-branch` is not. * `remote..annexUrl`