diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index b7d19721c6..6c5f5f75b8 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -23,11 +23,17 @@ 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,
-not to a particular filename on a particular git branch. 
-All files with the same content share the same metadata, which is
+not to a particular filename on a particular git branch.  More precisely,
+metadata is attached to the key used for the file, which can reflect
+file contents and/or name, depending on the key-value backend used for the file.
+All files with the same key share the same metadata, which is
 stored in the git-annex branch. If a file is edited, old
-metadata will be copied to the new contents when you [[git-annex-add]]
-the edited file. 
+metadata will be copied to the new key when you [[git-annex-add]]
+the edited file.  Note also that changes to a file's git-annex metadata will
+not be reflected in the git log of the file, since they are stored on the 
+git-annex branch. To attach metadata to a particular path,
+rather than a particular key, use .gitattributes .
+
 
 # OPTIONS