In the previous section, we focused on the essential operations and most common use cases. In this section, we will go a step further and give you additional tips on using the command-line interface, explain more options of the basic commands, and introduce a few more useful new commands.
The command-line interface of Bazaar has an excellent built-in help system, and all commands behave in a predictable, consistent way. Here, we highlight a few simple tips that should greatly improve your experience with the command-line interface.
A few flags are supported by all Bazaar commands:
-h,--help: This shows the help message. Also,bzr somecmd -handbzr help somecmdare equivalent.-v,--verbose: This shows the verbose output and displays more information than usual. Sometimes specifying the flag multiple times results in increased verbosity.-q,--quiet: This displays only errors and warnings.--usage: This shows usage messages and options.
Flags and command-line parameters can appear in any order. For example, the following are equivalent:
$ bzr log --line -r1 file.txt $ bzr log file.txt --line -r1 $ bzr log -r1 file.txt --line
Putting a space between a flag and its parameter is optional. For example, the following are equivalent:
$ bzr log -r1 $ bzr log -r 1
When using the long version of flags, for instance --revision instead of -r, the equal sign is optional. For example, the following are equivalent:
$ bzr log --revision=1 $ bzr log --revision 1
Many commands have shorter (or possibly more intuitive) aliases that can be used equivalently, for example:
The list of built-in aliases of each command is usually near the end of the help and usage messages.
With tags, you can give revisions a meaningful name, which can be especially useful to identify past milestones, or revisions that you frequently make references to for some reason. Once you assign a tag to a revision, you can refer to that revision using -rtag:somename in the various bzr log and bzr diff commands.
bzr tag v2.6: This assigns the tag "v2.6" to the current revisionbzr tag v2.6 -r117: This assigns the tag "v2.6" to revision 117bzr tag v2.6 -r119 --force: This reassigns the tag "v2.6" to revision 119bzr tag v2.6 --delete: This deletes the tag "v2.6"bzr tags: This shows all the tags in the current branch
Tags are stored in a branch, and are propagated in the various branch operations such as merge, push, and pull, which will be explained in the next chapter.
Tags must be unique within a branch. If you try to assign the same tag to a different revision, bzr will return an error. In this case, you can either delete the tag and recreate with a different revision, or use the --force flag, as in the preceding example.
In general, it is not a good practice to delete or reassign tags, especially when working together with others. As such, it is best to use unique tag names that will never need to be reassigned; generic names such as stable or testing should be avoided.
Many Bazaar commands accept a revision parameter, which can be specified using the -r and --revision flags.
In the most simple cases, revisions can be specified by their numbers, as shown in the output of the log command or in Bazaar Explorer, but there are many other interesting formats that are useful to know, such as using dates, tags, and other special symbols.
You can find the complete documentation of revision specification formats in bzr help revisionspec, where we highlight only a few interesting examples.
In addition to the revision number, you can specify revisions by date, tags, and other special symbols. For example:
bzr log -rdate:yesterday: This selects the first revision since yesterday. You can also usetodayortomorrowsimilarly.bzr log -rdate:2013-02-17: This selects the first revision since 2013-02-17.bzr log -rdate:2013-02-17,04:01:12: This selects the first revision since 2013-02-17, 4 AM 1 minute 12 seconds.bzr log -rtag:v2.6: This selects the revision named by the tag "v2.6".bzr log -rbefore:date:today: This selects the first revision before the specified date.bzr log -rbefore:3: This selects the first revision before the specified revision number.bzr log -rlast:1: This selects the last revision.bzr log -rlast:2: This selects the second to last revision.bzr log -r-1: This selects the last revision.bzr log -r-2: This selects the second to last revision.
Actually, in most cases the date and tag keywords can be omitted; Bazaar can figure out that you are referring to dates and tags. This is especially useful when using the before: keyword, thus allowing a shorter expression.
Depending upon the command, a range of revisions may make sense, and can be specified using the -r and --revision flags in the format N..M. For example:
$ bzr log -rbefore:today..last:1
The revisions N and M can be any valid single revision specifier, and both N and M may be omitted. For example these are all valid revision ranges:
However, be warned that depending upon the Bazaar operation, ranges may be interpreted differently.
In case of the log command, the range is a sequence of log messages, and the range is considered closed. That is, range 2..4 includes revisions 2, 3, and 4. Also, the end revision must be higher than the start revision.
In contrast, in case of the diff command, the range is a change between revisions, and is considered open-ended, excluding the beginning of the range. That is, range 2..4 includes the changes done in revisions 3 and 4 but not in 2. The range can also be reversed, with the start revision higher than the end revision. In this case, the direction of changes is also reversed. For example, range 4..2 includes the changes done in revisions 3 and 2 but not in 4, as if changing the project's state from revision 4 to revision 2.
We have already seen how to view the differences of pending changes in the working tree that are not yet committed to the repository. Another very common need is to view the differences between any two revisions, or similarly, a past revision and the working tree.
In all the comparison operations, you can specify a list of files and directories to see only the subset of all changes involving those files. If you do not specify any file parameters, Bazaar will display all the changes between the two compared revisions.
At the time of this writing, the Diff view of Bazaar Explorer does not have a user interface to choose the revisions to compare. A workaround is to launch the Diff view from the command line using the bzr qdiff command. For all examples in this chapter, you can simply replace all occurrences of bzr diff with bzr qdiff to view the output in Bazaar Explorer's more friendly format, rather than in a terminal window.
To compare a past revision and the current state of the working tree, run the
diff command and specify the past revision. For example:
$ bzr diff -r3 menu.txt === modified file 'menu.txt' --- menu.txt 2013-02-16 18:17:48 +0000 +++ menu.txt 2013-02-17 23:16:51 +0000 @@ -15,3 +15,4 @@ - Beef burrito - Mixed burrito - Onion soup +- Tacos
An important detail that is easy to overlook is that the diff command shows the changes that were recorded after the specified revision; it does not include the changes in the revision itself. Take a look at the following example:
$ bzr log --line menu.txt 4: Janos Gyerik 2013-02-17 correction in text files and map images 2: Janos Gyerik 2013-02-16 added guest list, menu and map files $ bzr diff -r4 menu.txt $
That is, in our sample project, menu.txt was last modified in revision 4, but these changes will not be included in the diff command output if we specify revision 4; for that, we will have to specify revision 3.
Another important point is that when using the diff command this way, it compares the past revision not with the latest revision, but with the current state of the working tree. In other words, the pending changes in the working tree will be part of the output.
Specifying the last revision is equivalent to not specifying a revision at all, comparing the last revision with the current state of the working tree.
To view the differences between two revisions, you must specify the revisions as a range using the -r or --revision flags, in the format START..END. The diff command will show the changes it would take to go from revision START to revision END.
It is important to remember that the changes in revision START itself will not be included in the output, because it does not fall within the definition of how the diff command works. To include changes in that revision, you must specify a previous revision, for example START-1, or by using the before keyword like this: before:START.
The order of the two revisions in the range is significant. If the range is N..M, the diff command will show the changes going from N to M (not including the changes in revision N itself), and if you reverse the end points of the range, then the diff command will show the changes going from M to N (not including the changes in revision M itself).
This is a special case of comparing any two revisions, using a range of two revisions, where the end revision is equal to start+1. A convenient shortcut for this case is the -c or --change flag, that specify the revision whose changes we're interested in. For example, you can see the changes in revision 4 as follows:
$ bzr diff -c4 menu.txt
This is equivalent to:
$ bzr diff -r3..4 menu.txt
This is also the same as viewing the diff output of selected files in selected revisions in the Log view of Bazaar Explorer.
Keeping backups is always a good idea. Using version control for your project gives you a lot of safety already—any accidental changes can be restored from a past revision. However, if your hard disk crashes the .bzr directory, your entire repository will be lost with it too.
The bzr push command is normally used when working with local or remote branches, which will be explained in later chapters. Incidentally, it is also an excellent and very simple way to take a backup. For example:
$ bzr push /media/backups/dev/dinner-party --create-prefix Created new branch.
This command creates a perfect clone of the working tree as a new branch at the specified location. The path can be any suitable location where you would like to put the clone, ideally a different hard disk. The --create-prefix flag is useful if the parent directory of the specified path does not exist, otherwise the flag is optional and will do nothing.
Once you created the clone, you can re-run bzr push again at any time to copy the new revisions to it. You don't need to specify the path again, Bazaar remembers your original push target.