diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index a672b104ce..a08c26af91 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -22,6 +22,14 @@ contains the date the field was last changed. Unlike other metadata,
 this cannot be directly modified by this command. It is updated
 automatically.
 
+Note that the metadata is attached to the particular content of a file
+(or rather to a particular [key](http://git-annex.branchable.com/backends/)),
+not to a particular file on a particular git branch.  All files with given
+content share the same metadata, which is stored on the
+[git-annex branch](http://git-annex.branchable.com/internals#The_git-annex_branch).
+If a file is [edited](http://git-annex.branchable.com/git-annex-unlock/),
+old metadata will be copied to the new contents when you [[git-annex-add]] the edited file. 
+
 # OPTIONS
 
 * `-g field` / `--get field`
diff --git a/doc/internals.mdwn b/doc/internals.mdwn
index 2074d52e95..47a809ad63 100644
--- a/doc/internals.mdwn
+++ b/doc/internals.mdwn
@@ -69,6 +69,7 @@ It will be re-created as necessary.
 git-annex uses this to journal changes to the git-annex branch,
 before committing a set of changes.
 
+<a name="The_git-annex_branch"></a>
 ## The git-annex branch
 
 This branch is managed by git-annex, with the contents listed below.