1 files changed, 103 insertions, 0 deletions
diff --git a/doc/en/user-guide/browsing_history.txt b/doc/en/user-guide/browsing_history.txt
new file mode 100644
index 0000000..c805b1f
--- /dev/null
+++ b/doc/en/user-guide/browsing_history.txt
@@ -0,0 +1,103 @@
+Browsing history
+================
+
+bzr log
+-------
+
+The ``bzr log`` command shows a list of previous revisions.
+
+As with ``bzr diff``, ``bzr log`` supports the ``-r`` argument::
+
+    % bzr log -r 1000..          # Revision 1000 and everything after it
+    % bzr log -r ..1000          # Everything up to and including r1000
+    % bzr log -r 1000..1100      # changes from 1000 to 1100
+    % bzr log -r 1000            # The changes in only revision 1000
+
+Viewing merged revisions
+------------------------
+
+As distributed VCS tools like Bazaar make merging much easier than
+it is in central VCS tools, the history of a branch may often contain
+lines of development splitting off the mainline and merging back
+in at a later time. Technically, the relationship between the
+numerous revision nodes is known as a Directed Acyclic Graph or
+DAG for short.
+
+In many cases, you typically want to see the mainline first and drill
+down from there. The default behaviour of log is therefore to show
+the mainline and indicate which revisions have nested merged revisions.
+To explore the merged revisions for revision X, use the following command::
+
+  bzr log -n0 -rX
+
+To see all revisions and all their merged revisions::
+
+  bzr log -n0
+
+Note that the -n option is used to indicate the number of levels to display
+where 0 means all. If that is too noisy, you can easily adjust the number
+to only view down so far. For example, if your project is structured with
+a top level gatekeeper merging changes from team gatekeepers, ``bzr log``
+shows what the top level gatekeeper did while ``bzr log -n2`` shows what
+the team gatekeepers did. In the vast majority of cases though, ``-n0``
+is fine.
+
+Tuning the output
+-----------------
+
+The ``log`` command has several options that are useful for tuning
+the output. These include:
+
+ * ``--forward`` presents the log in chronological order, i.e. the
+   most recent revisions are displayed last.
+
+ * the ``--limit`` option controls the maximum number of revisions displayed.
+
+See the online help for the log command or the User Reference for more
+information on tuning the output.
+
+Viewing the history for a file
+------------------------------
+
+It is often useful to filter the history so that it only
+applies to a given file. To do this, provide the filename
+to the ``log`` command like this::
+
+  bzr log foo.py
+
+Viewing an old version of a file
+--------------------------------
+
+To get the contents of a file at a given version, use the
+``cat`` command like this::
+
+  bzr cat -r X file
+
+where ``X`` is the revision identifier and ``file`` is
+the filename. This will send output to the standard output
+stream so you'll typically want to pipe the output through
+a viewing tool (like ``less`` or ``more``) or redirect it
+like this::
+
+  bzr cat -r -2 foo.py | less
+  bzr cat -r 1 foo.py > /tmp/foo-1st-version.py
+
+Graphical history viewers
+-------------------------
+
+History browsing is one area where GUI tools really make life easier.
+Bazaar has numerous plug-ins that provide this capability including
+QBzr and bzr-gtk. See `Using plugins <plugins.html>`_ for details on how to install
+these if they are not already installed.
+
+To use the graphical viewer from QBzr::
+
+  bzr qlog
+
+To use the graphical viewer from bzr-gtk::
+
+  bzr viz
+
+``viz`` is actually a built-in alias for ``visualize`` so use the longer
+command name if you prefer.
+