Recording changes
=================

bzr commit
----------

When the working tree state is satisfactory, it can be **committed** to
the branch, creating a new revision holding a snapshot of that state.

The **commit** command takes a message describing the changes in the
revision.  It also records your userid, the current time and timezone, and
the inventory and contents of the tree.  The commit message is specified
by the ``-m`` or ``--message`` option. You can enter a multi-line commit
message; in most shells you can enter this just by leaving the quotes open
at the end of the line.

::

    % bzr commit -m "added my first file"

You can also use the ``-F`` option to take the message from a file.  Some
people like to make notes for a commit message while they work, then
review the diff to make sure they did what they said they did.  (This file
can also be useful when you pick up your work after a break.)

Message from an editor
----------------------

If you use neither the ``-m`` nor the ``-F`` option then bzr will open an
editor for you to enter a message.  The editor to run is controlled by
your ``$VISUAL`` or ``$EDITOR`` environment variable, which can be overridden
by the ``editor`` setting in ``~/.bazaar/bazaar.conf``; ``$BZR_EDITOR`` will
override either of the above mentioned editor options.  If you quit the
editor without making any changes, the commit will be cancelled.

The file that is opened in the editor contains a horizontal line. The part
of the file below this line is included for information only, and will not
form part of the commit message. Below the separator is shown the list of
files that are changed in the commit. You should write your message above
the line, and then save the file and exit.

If you would like to see the diff that will be committed as you edit the
message you can use the ``--show-diff`` option to ``commit``. This will include
the diff in the editor when it is opened, below the separator and the
information about the files that will be committed. This means that you can
read it as you write the message, but the diff itself wont be seen in the
commit message when you have finished. If you would like parts to be
included in the message you can copy and paste them above the separator.

Selective commit
----------------

If you give file or directory names on the commit command line then only
the changes to those files will be committed.  For example::

    % bzr commit -m "documentation fix" commit.py

By default bzr always commits all changes to the tree, even if run from a
subdirectory.  To commit from only the current directory down, use::

    % bzr commit .

Giving credit for a change
--------------------------

If you didn't actually write the changes that you are about to commit, for instance
if you are applying a patch from someone else, you can use the ``--author`` commit
option to give them credit for the change::

    % bzr commit --author "Jane Rey <jrey@example.com>"

The person that you specify there will be recorded as the "author" of the revision,
and you will be recorded as the "committer" of the revision.

If more than one person works on the changes for a revision, for instance if you
are pair-programming, then you can record this by specifying ``--author`` multiple
times::

    % bzr commit --author "Jane Rey <jrey@example.com>" \
        --author "John Doe <jdoe@example.com>"