git-annex - documentation clarification - I've had data loss

[Matthew Hannigan]

Not sure you'd call this a docs bug; more like 90% my fault.
Just posting in case it might help someone avoid the same mistake.

I used git annex on an external usb disk of mine.  When I read the
docs, I took the following:

"When you add a file to the annex and commit it, only a symlink to the
annexed content is committed"
(http://git-annex.branchable.com/walkthrough/#index3h2)

to mean that the file are are left intact, in-situ and what was stored
is just metadata about the file.
(yep, I didn't even read the end of the sentence apparently; this was
a while ago)

Anyway, time passes, and I decide to move all this content over to a
different disk.
I just used drag and drop from a gui (not sure whether windows or
linux) and of course the select doesn't pick up the .git directory.

Next I reformated the disk, and get a funny feeling that the copy went
a little too fast ...


Can I suggest that the following wording be changed from this:
"When you add a file to the annex and commit it, only a symlink to the
annexed content is committed. The content itself is stored in
git-annex's backend."

 to this:
When you add a file to the annex, the content is moved to git-annex's
backend (.git/annex/..) and replaced with a symlink.  The commit only
commits the symlink.

The http://git-annex.branchable.com/how_it_works/ page might be
improved the same way.
It currently says
"The contents of large files are not stored in git, only the names of
the files and some other metadata remain there."
which is strictly true but might lead others to make the same mistaken
assumption that I did.

Regards,
Matt