--- a/mercurial/commands.py	Wed Jun 15 17:10:26 2011 +0200
+++ b/mercurial/commands.py	Wed Jun 15 17:25:58 2011 +0200
@@ -765,6 +765,12 @@
     Use the command :hg:`update` to switch to an existing branch. Use
     :hg:`commit --close-branch` to mark this branch as closed.
 
+    .. note::
+
+       Branch names are permanent. Use :hg:`bookmark` to create a
+       light-weight bookmark instead. See :hg:`help glossary` for more
+       information about named branches and bookmarks.
+
     Returns 0 on success.
     """