update re git-annex branch direct modification

Branch.hs

@@ -164,6 +164,8 @@ updateRef ref
 	| ref == fullname = return Nothing
 	| otherwise = do
 		g <- Annex.gitRepo
+		-- checking with log to see if there have been changes
+		-- is less expensive than always merging
 		diffs <- liftIO $ Git.pipeRead g [
 			Param "log",
 			Param (name++".."++ref),
@@ -176,6 +178,12 @@ updateRef ref
 				-- By passing only one ref, it is actually
 				-- merged into the index, preserving any
 				-- changes that may already be staged.
+				--
+				-- However, any changes in the git-annex
+				-- branch that are *not* reflected in the
+				-- index will be removed. So, documentation
+				-- advises users not to directly modify the
+				-- branch.
 				liftIO $ GitUnionMerge.merge g [ref]
 				return $ Just ref
 

Locations.hs

@@ -105,6 +105,11 @@ gitAnnexBadLocation r key = gitAnnexBadDir r </> keyFile key
 gitAnnexUnusedLog :: FilePath -> Git.Repo -> FilePath
 gitAnnexUnusedLog prefix r = gitAnnexDir r </> (prefix ++ "unused")
 
+{- .git/annex/journal/ is used to journal changes made to the git-annex
+ - branch -}
+gitAnnexJournalDir :: Git.Repo -> FilePath
+gitAnnexJournalDir r = addTrailingPathSeparator $ gitAnnexDir r </> "journal"
+
 {- Checks a symlink target to see if it appears to point to annexed content. -}
 isLinkToAnnex :: FilePath -> Bool
 isLinkToAnnex s = ("/.git/" ++ objectDir) `isInfixOf` s

doc/internals.mdwn

@@ -21,9 +21,14 @@ deleting or changing the file contents.
 
 This branch is managed by git-annex, with the contents listed below.
 
-Note that it assumes only it will modify the branch. If you go in and make
-changes, be sure to remove `.git/index.git-annex` before running git-annex,
-otherwise it will probably revert your changes in its next commit to the branch.
+Note that git-annex assumes only it will modify this branch. If you go in
+and make changes directly, it will probably revert your changes in its next
+commit to the branch.
+
+The best way to make changes to the git-annex branch is instead
+to create a branch of it, with a name like "my/git-annex", and then
+use "git annex merge" to automerge your branch into the main git-annex
+branch.
 
 ### `uuid.log`