Rev 3106: Clean-up of User Guide for 1.0 (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu Dec 13 08:37:44 GMT 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3106
revision-id:pqm at pqm.ubuntu.com-20071213083735-30doieica3xb8tcp
parent: pqm at pqm.ubuntu.com-20071213021422-mq0sexod7cz09yd6
parent: ian.clatworthy at internode.on.net-20071213073849-av4rf6pcvalr4azd
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-12-13 08:37:35 +0000
message:
Clean-up of User Guide for 1.0 (Ian Clatworthy)
modified:
doc/en/user-guide/authentication_conf.txt authentication_conf.-20071104135035-glfv0ri355tyg1nf-1
doc/en/user-guide/configuration.txt configuration.txt-20060314161707-868350809502af01
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/plugins.txt plugins.txt-20060314145616-525099a747f3ffdd
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/server.txt server.txt-20060913044801-h939fvbwzz39gf7g-1
doc/en/user-guide/setting_up_email.txt setting_up_email.txt-20060314161707-fd242c8944346173
doc/en/user-guide/specifying_revisions.txt specifying_revisions.txt-20060314161707-19deb139101bea33
doc/en/user-guide/version_info.txt version_info.txt-20060921215543-gju6o5xdic8w25np-1
------------------------------------------------------------
revno: 3105.1.1
revision-id:ian.clatworthy at internode.on.net-20071213073849-av4rf6pcvalr4azd
parent: pqm at pqm.ubuntu.com-20071213021422-mq0sexod7cz09yd6
parent: ian.clatworthy at internode.on.net-20071213073010-cv81py4kq4f2m390
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: ianc-integration
timestamp: Thu 2007-12-13 17:38:49 +1000
message:
Clean-up of User Guide for 1.0 (Ian Clatworthy)
modified:
doc/en/user-guide/authentication_conf.txt authentication_conf.-20071104135035-glfv0ri355tyg1nf-1
doc/en/user-guide/configuration.txt configuration.txt-20060314161707-868350809502af01
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/plugins.txt plugins.txt-20060314145616-525099a747f3ffdd
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
doc/en/user-guide/server.txt server.txt-20060913044801-h939fvbwzz39gf7g-1
doc/en/user-guide/setting_up_email.txt setting_up_email.txt-20060314161707-fd242c8944346173
doc/en/user-guide/specifying_revisions.txt specifying_revisions.txt-20060314161707-19deb139101bea33
doc/en/user-guide/version_info.txt version_info.txt-20060921215543-gju6o5xdic8w25np-1
------------------------------------------------------------
revno: 3104.2.7
revision-id:ian.clatworthy at internode.on.net-20071213073010-cv81py4kq4f2m390
parent: ian.clatworthy at internode.on.net-20071213033843-dyorvg8qp6i15cph
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 17:30:10 +1000
message:
feedback from poolie
modified:
doc/en/user-guide/configuration.txt configuration.txt-20060314161707-868350809502af01
doc/en/user-guide/specifying_revisions.txt specifying_revisions.txt-20060314161707-19deb139101bea33
------------------------------------------------------------
revno: 3104.2.6
revision-id:ian.clatworthy at internode.on.net-20071213033843-dyorvg8qp6i15cph
parent: ian.clatworthy at internode.on.net-20071213030745-qhw4i0g5nbspx0ws
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 13:38:43 +1000
message:
Improve Exporting version information
modified:
doc/en/user-guide/version_info.txt version_info.txt-20060921215543-gju6o5xdic8w25np-1
------------------------------------------------------------
revno: 3104.2.5
revision-id:ian.clatworthy at internode.on.net-20071213030745-qhw4i0g5nbspx0ws
parent: ian.clatworthy at internode.on.net-20071213020800-j4dtl8y4jy902frr
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 13:07:45 +1000
message:
fix some broken links and make doc more Windows user friendly
modified:
doc/en/user-guide/authentication_conf.txt authentication_conf.-20071104135035-glfv0ri355tyg1nf-1
doc/en/user-guide/configuration.txt configuration.txt-20060314161707-868350809502af01
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
doc/en/user-guide/plugins.txt plugins.txt-20060314145616-525099a747f3ffdd
doc/en/user-guide/setting_up_email.txt setting_up_email.txt-20060314161707-fd242c8944346173
------------------------------------------------------------
revno: 3104.2.4
revision-id:ian.clatworthy at internode.on.net-20071213020800-j4dtl8y4jy902frr
parent: ian.clatworthy at internode.on.net-20071213012803-2rn4lr2b1yvmz6v5
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 12:08:00 +1000
message:
make it clear the Reference has the details of revision spec formats
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/specifying_revisions.txt specifying_revisions.txt-20060314161707-19deb139101bea33
------------------------------------------------------------
revno: 3104.2.3
revision-id:ian.clatworthy at internode.on.net-20071213012803-2rn4lr2b1yvmz6v5
parent: ian.clatworthy at internode.on.net-20071213010238-rfabualcymi1f71j
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 11:28:03 +1000
message:
make Choosing a shared repsoitory layout an appendix
modified:
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
------------------------------------------------------------
revno: 3104.2.2
revision-id:ian.clatworthy at internode.on.net-20071213010238-rfabualcymi1f71j
parent: ian.clatworthy at internode.on.net-20071213010154-vpvh7rcte50fs8kn
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 11:02:38 +1000
message:
update status of smart server development
modified:
doc/en/user-guide/server.txt server.txt-20060913044801-h939fvbwzz39gf7g-1
------------------------------------------------------------
revno: 3104.2.1
revision-id:ian.clatworthy at internode.on.net-20071213010154-vpvh7rcte50fs8kn
parent: pqm at pqm.ubuntu.com-20071211175118-s94sizduj201hrs5
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-fixes
timestamp: Thu 2007-12-13 11:01:54 +1000
message:
switch now works on normal checkouts
modified:
doc/en/user-guide/reusing_a_checkout.txt reusing_a_checkout.t-20071123055134-k5x4ekduci2lbn36-3
=== modified file 'doc/en/user-guide/authentication_conf.txt'
--- a/doc/en/user-guide/authentication_conf.txt 2007-11-14 03:50:56 +0000
+++ b/doc/en/user-guide/authentication_conf.txt 2007-12-13 03:07:45 +0000
@@ -6,7 +6,7 @@
------
Many different authentication policies can be described in the
-``$HOME/.bazaar/authentication.conf`` file but a particular user should need
+``authentication.conf`` file but a particular user should need
only a few definitions to cover his needs without having to specify a user and
a password for every branch he uses.
@@ -112,7 +112,7 @@
The general rules for `configuration files`_ apply except for the variable
policies.
-.. _configuration files: configuration.html
+.. _configuration files: #configuration-reference
Each section describes an authentication definition.
=== modified file 'doc/en/user-guide/configuration.txt'
--- a/doc/en/user-guide/configuration.txt 2007-11-23 06:06:43 +0000
+++ b/doc/en/user-guide/configuration.txt 2007-12-13 07:30:10 +0000
@@ -1,8 +1,6 @@
Configuration reference
=======================
-Information on how to configure Bazaar.
-
.. TODO: Should have some explanation of why you'd want things in
.. branch.conf.
@@ -31,8 +29,9 @@
~~~~~~~~~~~~~~~
Control whether SIGQUIT behaves normally or invokes a breakin debugger.
-0 = Standard SIGQUIT behavior
-1 = Invoke breakin debugger (default)
+
+* 0 = Standard SIGQUIT behavior (normally, exit with a core dump)
+* 1 = Invoke breakin debugger (default)
BZR_HOME
~~~~~~~~
@@ -48,15 +47,16 @@
~~~~~~~
Control whether to launch a debugger on error.
-0 = Standard behavior
-1 = Launch debugger
+
+* 0 = Standard behavior
+* 1 = Launch debugger
BZR_REMOTE_PATH
~~~~~~~~~~~~~~~
Path to the Bazaar executable to use when using the bzr+ssh protocol.
-See also the ``bzr_remote_path`` configuration value
+See also the ``bzr_remote_path`` configuration value.
BZR_EDITOR
~~~~~~~~~~
@@ -80,8 +80,12 @@
Location
~~~~~~~~
-Configuration files are located in ``$HOME/.bazaar`` and are
-sometimes referred to as ``ini files``:
+Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
+``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
+Windows. (You can check the location for your system by using
+``bzr version``.)
+
+There are three primary configuration files in this location:
* ``bazaar.conf`` describes default configuration options,
@@ -174,7 +178,7 @@
The main configuration file, bazaar.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one
+``bazaar.conf`` only allows one
section called ``[DEFAULT]``. This default section contains the default
configuration options for all branches. The default section can be
overriden by providing a branch-specific section in ``locations.conf``.
@@ -191,7 +195,7 @@
The branch location configuration file, locations.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for
+``locations.conf`` allows one to specify overriding settings for
a specific branch. The format is almost identical to the default section in
bazaar.conf with one significant change: The section header, instead of saying
default, will be the path to a branch that you wish to override a value
@@ -210,7 +214,7 @@
The authentication configuration file, authentication.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``$HOME/.bazaar/authentication.conf`` allows one to specify credentials for
+``authentication.conf`` allows one to specify credentials for
remote servers. This can be used for all the supported transports and any part
of bzr that requires authentication (smtp for example).
@@ -218,9 +222,8 @@
variable policies which don't apply.
For more information on the possible uses of the authentication configuration
-file see the `authentication configuration file documentation`_.
+file see `Configuring authentication`_.
-.. _authentication configuration file documentation: authentication_conf.html
Common variable options
-----------------------
@@ -238,7 +241,8 @@
The path of the editor that you wish to use if *bzr commit* is run without
a commit message. This setting is trumped by the environment variable
-``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.
+``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
+variables.
check_signatures
~~~~~~~~~~~~~~~~
@@ -358,10 +362,11 @@
not publically-accessible). Used (and set) by ``bzr send``.
-Branch 6 options
-----------------
+Branch type specific options
+----------------------------
-These options apply only to branches that use the "dirstate-tags" format. They
+These options apply only to branches that use the ``dirstate-tags`` or
+later format. They
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
manually set in ``locations.conf`` or ``bazaar.conf``.
@@ -397,4 +402,3 @@
If set to "True", the branch should act as a checkout, and push each commit to
the bound_location. This option is normally set by ``bind``/``unbind``.
-
=== modified file 'doc/en/user-guide/core_concepts.txt'
--- a/doc/en/user-guide/core_concepts.txt 2007-12-04 11:51:38 +0000
+++ b/doc/en/user-guide/core_concepts.txt 2007-12-13 02:08:00 +0000
@@ -38,6 +38,9 @@
While these identifiers are necessary for internal use and external tool
integration, branch-specific *revision numbers* are the preferred
interface for humans. Typical revision numbers are 1, 42 and 2977.1.59.
+See `Specifying revisions`_ in the appendices for a closer look at
+the numerous ways that revisions and ranges of revisions can be specified
+in Bazaar.
.. *TODO: add diagram*
=== modified file 'doc/en/user-guide/http_smart_server.txt'
--- a/doc/en/user-guide/http_smart_server.txt 2007-11-14 03:50:56 +0000
+++ b/doc/en/user-guide/http_smart_server.txt 2007-12-13 03:07:45 +0000
@@ -10,7 +10,7 @@
For more information on the smart server, and other ways to configure it
see the main `smart server documentation`_.
-.. _smart server documentation: server.html
+.. _smart server documentation: #running-a-smart-server
Example
-------
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2007-11-28 00:07:56 +0000
+++ b/doc/en/user-guide/index.txt 2007-12-13 01:28:03 +0000
@@ -83,13 +83,13 @@
.. include:: hooks.txt
.. include:: version_info.txt
.. include:: bug_trackers.txt
-.. include:: shared_repository_layouts.txt
Appendices
##########
.. include:: specifying_revisions.txt
+.. include:: shared_repository_layouts.txt
.. include:: conflicts.txt
.. include:: configuration.txt
.. include:: setting_up_email.txt
=== modified file 'doc/en/user-guide/plugins.txt'
--- a/doc/en/user-guide/plugins.txt 2007-11-30 04:28:32 +0000
+++ b/doc/en/user-guide/plugins.txt 2007-12-13 03:07:45 +0000
@@ -34,11 +34,11 @@
-----------------------
Installing a plugin is very easy! If not already created, create a
-``plugins`` directory under your Bazaar configuration directory
-($BZR_HOME), i.e. ``~/.bazaar/`` on Linux and
+``plugins`` directory under your Bazaar configuration directory,
+``~/.bazaar/`` on Linux and
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0\``
-on Windows. Within this directory, each plugin is placed in its own
-subdirectory.
+on Windows. Within this directory (referred to as $BZR_HOME below),
+each plugin is placed in its own subdirectory.
Plugins work particularly well with Bazaar branches. For example, to
install the bzrtools plugins for your main user account on Linux,
@@ -47,11 +47,11 @@
bzr branch http://panoramicfeedback.com/opensource/bzr/bzrtools
~/.bazaar/plugins/bzrtools
-When installing plugins the directories that you install them in must
+When installing plugins, the directories that you install them in must
be valid python identifiers. This means that they can only contain
certain characters, notably they cannot contain hyphens (``-``). Rather
-than installing ``bzr-gtk`` to ``~/.bazaar/plugins/bzr-gtk``, install it
-to ``~/.bazaar/plugins/gtk``.
+than installing ``bzr-gtk`` to ``$BZR_HOME/plugins/bzr-gtk``, install it
+to ``$BZR_HOME/plugins/gtk``.
Alternative plugin locations
----------------------------
=== modified file 'doc/en/user-guide/publishing_a_branch.txt'
--- a/doc/en/user-guide/publishing_a_branch.txt 2007-11-23 05:52:03 +0000
+++ b/doc/en/user-guide/publishing_a_branch.txt 2007-12-13 01:28:03 +0000
@@ -17,7 +17,11 @@
bzr init-repo --no-trees sftp://centralhost/srv/bzr/X-repo/
You can think of this step as similar to setting up a new cvsroot or
-Subversion repository.
+Subversion repository. However, Bazaar gives you more flexibility
+in how branches may be organised in your repository. See
+`Choosing a shared repository layout`_ in the appendices for
+guidelines and examples.
+
Starting a central branch
-------------------------
=== modified file 'doc/en/user-guide/reusing_a_checkout.txt'
--- a/doc/en/user-guide/reusing_a_checkout.txt 2007-12-04 12:56:31 +0000
+++ b/doc/en/user-guide/reusing_a_checkout.txt 2007-12-13 01:01:54 +0000
@@ -20,6 +20,7 @@
configured into numerous development and testing tools. Once
again, reusing a checkout across multiple branches can help.
+
Changing where a branch is bound to
-----------------------------------
@@ -34,28 +35,28 @@
3. Make your checkout a copy of the desired branch by using
the ``update`` command followed by the ``revert`` command.
-Note that simply binding to a new branch
-and running ``update`` merges in your local changes. You need
+Note that simply binding to a new branch and running ``update``
+merges in your local changes, both committed and uncommitted. You need
to decide whether to keep them or not by running either ``revert``
or ``commit``.
-An alternative to the bind+update recipe is:
-
- 1. Use the ``unbind`` command to turn the checkout into a normal branch.
-
- 2. Run ``bzr pull --overwrite URL`` to make the branch a mirror of
- a new URL.
-
- 3. Run ``bzr bind URL`` to bind to that URL.
+An alternative to the bind+update recipe is using the ``switch``
+command. This is basically the same as removing the existing
+branch and running ``checkout`` again on the new location, except
+that any uncommitted changes in your tree are merged in.
+
+Note: As ``switch`` can potentially throw away committed changes in
+order to make a checkout an accurate cache of a different bound branch,
+it will fail by design if there are changes which have been committed
+locally but are not yet committed to the most recently bound branch.
+To truly abandon these changes, use the ``--force`` option.
+
Switching a lightweight checkout
--------------------------------
-If you have a lightweight checkout, there is no local history
-to worry about. In this case, you
-can simply alter the branch that the checkout (i.e.
-working tree) is referring to by using the ``switch`` command.
-
+With a lightweight checkout, there are no local commits and ``switch``
+effectively changes which branch the working tree is associated with.
One possible setup is to use a lightweight checkout in combination
with a local tree-less repository. This lets you switch what you
are working on with ease. For example::
@@ -80,15 +81,6 @@
bzr switch ../X-trunk
(go back to working on the trunk)
-In many ways, ``switch`` operates like ``update`` in that it
-refreshes your working tree and merges in any local changes you
-have made. The primary different is that ``switch`` requires
-a branch location and it is only supported (currently) on
-lightweight checkouts. ``switch`` also only preserves
-uncommitted changes while update keeps committed ones.
-
Note: The branches may be local only or they may be bound to
remote ones (by creating them with ``checkout`` or by using ``bind``
-after creating them with ``branch``). ``switch`` and ``bind`` are
-similar but different: switch controls which branch the working tree
-refers to while ``bind`` associates a remote branch to the local one.
+after creating them with ``branch``).
=== modified file 'doc/en/user-guide/server.txt'
--- a/doc/en/user-guide/server.txt 2007-11-14 03:50:56 +0000
+++ b/doc/en/user-guide/server.txt 2007-12-13 01:02:38 +0000
@@ -1,5 +1,5 @@
-Running a Bazaar server
-=======================
+Running a smart server
+======================
Bazaar does not require a specialised server because it operates over HTTP, FTP
or SFTP. There is an optional smart server that can be invoked over SSH, from
@@ -17,22 +17,21 @@
Bazaar supports writing over FTP, SFTP and (via a plugin) over HTTP-WebDAV.
-High-performance server
------------------------
+High-performance smart server
+-----------------------------
-The high-performance server is currently in development. It provides a dumb
-server facility as well as additional capabilities which allow the version of
-bzr that accompanies this documentation to perform some operations much faster
-than via dumb servers. In future releases of bzr the range of operations that
-are improved by using the high-performance server will increase.
+The high-performance smart server (hpss) performs certain operations much faster
+than dumb servers are capable of. In future releases, the range of operations
+that are improved by using the smart server will increase as we continue to
+tune performance.
To maintain the highest security possible, the current
-high-performance server provides read-only access by default. To
+smart server provides read-only access by default. To
enable read-write access, run it with ``--allow-writes``. When using
the SSH access method, bzr automatically runs with with the
``--allow-writes`` option.
-The server can be configured to run in three different ways:
+The alternative ways of configuring a smart server are explained below.
SSH
~~~
=== modified file 'doc/en/user-guide/setting_up_email.txt'
--- a/doc/en/user-guide/setting_up_email.txt 2007-11-27 21:34:11 +0000
+++ b/doc/en/user-guide/setting_up_email.txt 2007-12-13 03:07:45 +0000
@@ -30,13 +30,13 @@
The order of precedence is
- 1. If the ``$BZR_EMAIL`` environment variable is set.
+ 1. If the ``BZR_EMAIL`` environment variable is set.
#. If an email is set for your current branch in the ``locations.conf``
file.
#. If an email is set four your current branch in the
``.bzr/branch/branch.conf`` file.
#. If an email is set in the ``bazaar.conf`` default configuration file.
- #. If the `$EMAIL` environment variable is set.
+ #. If the `EMAIL` environment variable is set.
#. Bazaar will try to guess based on your username and the hostname.
To check on what Bazaar thinks your current email is, use the ``whoami``
@@ -61,24 +61,23 @@
Setting email via default configuration file
--------------------------------------------
-To use the default ini file, create the file ``$HOME/.bazaar/bazaar.conf`` (on
-Windows this is ``%APPDATA%\bazaar\2.0\bazaar.conf``) and set an email address
-as shown below. Please note that the word DEFAULT is case sensitive, and
-must be in upper-case.
+To use the default ini file, create or edit the ``bazaar.conf`` file (in
+``~/.bazaar/`` on Linix and in ``%APPDATA%\bazaar\2.0\`` in Windows)
+and set an email address as shown below. Please note that the word DEFAULT
+is case sensitive, and must be in upper-case.
::
[DEFAULT]
email=Your Name <name at isp.com>
-For more information on the ini file format, see ConfiguringBzr.
+For more information on the ini file format, see `Configuration reference`_.
Setting email on a per-branch basis
-----------------------------------
The second approach is to set email on a branch by branch basis by
-using the ``$HOME/.bazaar/locations.conf`` configuration file,
-thusly::
+using the ``locations.conf`` configuration file like this::
[/some/branch/location]
email=Your Name <name at other-isp.com>
@@ -88,8 +87,8 @@
Setting email via environment variable
--------------------------------------
-The final method Bazaar will use is checking for the ``$BZR_EMAIL``
-and ``$EMAIL`` environment variables. Generally, you would use this
+The final method Bazaar will use is checking for the ``BZR_EMAIL``
+and ``EMAIL`` environment variables. Generally, you would use this
method to override the email in a script context. If you would like
to set a general default, then please see the ini methods above.
=== modified file 'doc/en/user-guide/specifying_revisions.txt'
--- a/doc/en/user-guide/specifying_revisions.txt 2007-11-23 06:06:43 +0000
+++ b/doc/en/user-guide/specifying_revisions.txt 2007-12-13 07:30:10 +0000
@@ -1,13 +1,12 @@
-Revision specifiers
-===================
-
-Revision specs and ranges
--------------------------
-
-``bzr`` has a very expressive way to specify a revision, or a range of revisions.
-We'll take the example of the ``log`` command.
-
-To specify a range of revisions, use for example::
+Specifying revisions
+====================
+
+Revision identifiers and ranges
+-------------------------------
+
+Bazaar has a very expressive way to specify a revision or a range of revisions.
+To specify a range of revisions, the upper and lower bounds are separated by the
+``..`` symbol. For example::
$ bzr log -r 1..4
@@ -16,17 +15,21 @@
$ bzr log -r 1..
$ bzr log -r ..4
-Note:
- Omitting the lower bound doesn't work on versions of ``bzr`` prior to 0.14.
-
-Other commands, like ``bzr cat`` take only one revision, not a range, like::
+Some commands take only one revision, not a range. For example::
$ bzr cat -r 42 foo.c
-Available revision specs
-------------------------
-
-The revision, or the bounds of the range, can be one of
+In other cases, a range is required but you want the length of the range to
+be one. For commands where this is relevant, the ``-c`` option is used like this::
+
+ $ bzr diff -c 42
+
+
+Available revision identifiers
+------------------------------
+
+The revision, or the bounds of the range, can be given using
+different format specifications as shown below.
+----------------------+------------------------------------+
| argument type | description |
@@ -43,10 +46,20 @@
+----------------------+------------------------------------+
| **date**:*value* | first entry after a given date |
+----------------------+------------------------------------+
+ | **tag**:*value* | revision matching a given tag |
+ +----------------------+------------------------------------+
| **ancestor**:*path* | last merged revision from a branch |
+----------------------+------------------------------------+
| **branch**:*path* | latest revision on another branch |
+----------------------+------------------------------------+
+ | **submit**:*path* | common ancestor with submit branch |
+ +----------------------+------------------------------------+
+
+A brief introduction to some of these formats is given below.
+For complete details, see `Revision Identifiers`_ in the
+Bazaar User Reference.
+
+.. _Revision Identifiers: ../user-reference/bzr_man.html#revision-identifiers
Numbers
~~~~~~~
@@ -64,15 +77,6 @@
$ bzr log -r -10..
-revno, last
-~~~~~~~~~~~
-
-**revno**:*number*
- The same as *number*, except that negative numbers are not allowed.
-
-**last**:*number*
- The same as -''number''. **last:1** means the last commited revision.
-
revid
~~~~~
@@ -83,7 +87,6 @@
$ bzr log -r revid:Matthieu.Moy at imag.fr-20051026185030-93c7cad63ee570df
-
before
~~~~~~
=== modified file 'doc/en/user-guide/version_info.txt'
--- a/doc/en/user-guide/version_info.txt 2007-11-21 02:54:47 +0000
+++ b/doc/en/user-guide/version_info.txt 2007-12-13 03:38:43 +0000
@@ -1,24 +1,51 @@
Exporting version information
=============================
-Overview
---------
-
-This document describes ways of using ``bzr version-info`` as part of a
-build process to embed version information into a final project.
-
-
-Python project
---------------
-
-TODO: Figure out how to attach into ``setup.py``
+Getting the last revision number
+--------------------------------
+
+If you only need the last revision number in your build scripts, you can
+use the ``revno`` command to get that value like this::
+
+ $ bzr revno
+ 3104
+
+
+Getting more version information
+--------------------------------
+
+The ``version-info`` command can be used to output more information
+about the lastest version like this::
+
+ $ bzr version-info
+ revision-id: pqm at pqm.ubuntu.com-20071211175118-s94sizduj201hrs5
+ date: 2007-12-11 17:51:18 +0000
+ build-date: 2007-12-13 13:14:51 +1000
+ revno: 3104
+ branch-nick: bzr.dev
+
+You can easily filter that output using operating system tools or
+scripts. For example (on Linux/Unix)::
+
+ $ bzr version-info | grep ^date
+ date: 2007-12-11 17:51:18 +0000
+
+The ``--all`` option will actually dump version information about
+every revision if you need that information for more advanced
+post-processing.
+
+
+Python projects
+---------------
+
+.. TODO: Figure out how to attach into ``setup.py``
If using a Makefile to build your project, you can generate the version
information file as simply as::
library/_version.py:
- bzr version-info --format=python > library/_version.py
+ bzr version-info --format python > library/_version.py
This generates a file which contains 3 dictionaries:
@@ -39,6 +66,16 @@
map. This is also empty by default, and enabled only by ``--all``
or ``--include-file-revisions``.
+
+Projects in other languages
+---------------------------
+
+Support for dumping version information in other languages in currently
+in development. Please contact us on the mailing list about your
+requirements in this area. (As of the Bazaar 1.0 release date, some patches
+are available for other languages but are not yet merged into the core product.)
+
+
Check clean
-----------
More information about the bazaar-commits
mailing list