docs/changelog for write (#328, #448)

docs/changelog.rst

@@ -20,6 +20,10 @@ New features:
     ``copy``, ``move``, ``delete``, ``delete_file``, and ``tag`` options
     perform those actions.
 
+* The new built-in :ref:`write-cmd` command lets you update the metadata tags
+  for files, bringing them back into sync with your database. Thanks to Heinz
+  Wiesinger.
+
 * :doc:`/plugins/lastgenre`: The new ``multiple`` option has been replaced
   with the ``count`` option, which lets you limit the number of genres added
   to your music. (No more thousand-character genre fields!) Also, the

docs/reference/cli.rst

@@ -243,6 +243,28 @@ overridden by data from other tracks on the same album. This means that
 running the ``update`` command multiple times may show the same changes being
 applied.
 
+
+.. _write-cmd:
+
+write
+`````
+::
+
+    beet write [-ap] [QUERY]
+
+Write metadata from the database into files' tags.
+
+When you make changes to the metadata stored in beets' library database
+(during import or with the :ref:`modify-cmd` command, for example), you often
+have the option of storing changes only in the database, leaving your files
+untouched. The ``write`` command lets you later change your mind and write the
+contents of the database into the files.
+
+The ``-p`` option previews metadata changes without actually applying them.
+
+You can think of this command as the opposite of :ref:`update-cmd`.
+
+
 .. _stats-cmd:
 
 stats