docs/changelog for duplicate resolution (#164)

docs/changelog.rst

@@ -3,6 +3,13 @@ Changelog
 
 1.0b14 (in development)
 -----------------------
+* The importer now gives you **choices when duplicates are detected**.
+  Previously, when beets found an existing album or item in your library
+  matching the metadata on a newly-imported one, it would just skip the new
+  music to avoid introducing duplicates into your library. Now, you have three
+  choices: skip the new music (the previous behavior), keep both, or remove the
+  old music. See the :ref:`guide-duplicates` section in the autotagging guide
+  for details.
 * New :doc:`/plugins/m3uupdate`: Catalog imported files in an ``m3u`` playlist
   file for easy importing to other systems. Thanks to Fabrice Laporte.
 

docs/guides/tagger.rst

@@ -195,6 +195,26 @@ guessing---beets will show you the proposed changes and ask you to confirm
 them, just like the earlier example. As the prompt suggests, you can just hit
 return to select the first candidate.
 
+.. _guide-duplicates:
+
+Duplicates
+----------
+
+If beets finds an album or item in your library that seems to be the same as the
+one you're importing, you may see a prompt like this::
+
+    This album is already in the library!
+    [S]kip new, Keep both, Remove old?
+
+Beets wants to keep you safe from duplicates, which can be a real pain, so you
+have three choices in this situation. You can skip importing the new music,
+choosing to keep the stuff you already have in your library; you can keep both
+the old and the new music; or you can remove the existing music and choose the
+new stuff. If you choose that last "trump" option, any duplicates will be
+removed from your library database---and, if the corresponding files are located
+inside of your beets library directory, the files themselves will be deleted as
+well.
+
 Fingerprinting
 --------------