git-annex merge branch

* merge: When run with a branch parameter, merges from that branch.
  This is especially useful when using an adjusted branch, because
  it applies the same adjustment to the branch before merging it.

doc/git-annex-adjust.mdwn

@@ -24,6 +24,11 @@ To propagate commits from the adjusted branch back to the original branch,
 and to other repositories, as well as to merge in changes from other
 repositories, run `git annex sync`.
 
+When in an adjusted branch, using `git merge otherbranch` is often not
+ideal, because merging a non-adjusted branch may lead to unncessary
+merge conflicts, or add files in non-adjusted form. To avoid those
+problems, use `git annex merge otherbranch`.
+
 Re-running this command with the same options
 while inside the adjusted branch will update the adjusted branch
 as necessary (eg for `--hide-missing`), and will also propagate commits

doc/git-annex-import.mdwn

@@ -35,17 +35,23 @@ 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
+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 merge myremote/master
+	git annex merge myremote/master
 
-Note that you may need to 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
+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.
 

doc/git-annex-merge.mdwn

@@ -1,16 +1,21 @@
 # NAME
 
-git-annex merge - automatically merge changes from remotes
+git-annex merge - merge changes from remotes
 
 # SYNOPSIS
 
-git annex merge
+git annex merge [branch]
 
 # DESCRIPTION
 
-This performs the same merging (and merge conflict resolution)
-that is done by the sync command, but without pushing or pulling any
-data.
+When run without any parameters, this performs the same merging (and merge
+conflict resolution) that is done by the sync command, but without pushing
+or pulling any data.
+
+When a branch to merge is specified, this merges it, using the same merge
+conflict resolution as the sync command. This is especially useful on
+an adjusted branch, because it applies the same adjustment to the
+branch before merging it.
 
 When annex.resolvemerge is set to false, merge conflict resolution
 will not be done.
@@ -21,6 +26,8 @@ will not be done.
 
 [[git-annex-sync]](1)
 
+[[git-annex-adjust]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/tips/android_sync_with_adb.mdwn

@@ -57,7 +57,7 @@ for more details, and bear in mind that you can also use commands like
 these to only import from or export to the android device:
 
 	git annex import master:android --from android
-	git merge android/master
+	git annex merge android/master
 	git annex export master:android --to android
 
 ## sample workflows