From f98dde1b7ea81df5ce7e6980f3c19a87b3e8d240 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Mon, 25 Nov 2013 15:34:11 -0800
Subject: [PATCH] docs/changelog for write (#328, #448)

---
 docs/changelog.rst     |  4 ++++
 docs/reference/cli.rst | 22 ++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 3d4e707d4..b99965748 100644
--- a/docs/changelog.rst
+++ b/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
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index 4908b10b1..a37faf389 100644
--- a/docs/reference/cli.rst
+++ b/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