pager - Pipe commands producing long output to a pager (e.g. less)

Version Not specified
Branch Not specified
Home page http://bzr.oxygene.sk/bzr-plugins/pager
Owner luks
GNU/Linux Yes
Windows No
Mac OS X Yes

Plugin ‘bzrlib.plugins.pager’ has no docstring.

annotate

Purpose

Show the origin of each line in a file.

Usage

bzr annotate FILENAME

Options

--all Show annotations on all lines.
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
--long Show commit date in annotations.
--usage Show usage message and options.
--show-ids Show internal object ids.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-h, --help Show help message.

Description

This prints out the given file with an annotation on the left side indicating which revision, author and date introduced the change.

If the origin is the same for a run of consecutive lines, it is shown only at the top, unless the –all option is given.

Aliases

ann, blame, praise

cat

Purpose

Write the contents of a file as of a given revision to standard output.

Usage

bzr cat FILENAME

Options

-v, --verbose Display more information.
--name-from-revision
 The path name in the old tree.
-q, --quiet Only display errors and warnings.
--filters Apply content filters to display the convenience form.
--usage Show usage message and options.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-h, --help Show help message.

Description

If no revision is nominated, the last revision is used.

Note: Take care to redirect standard output when using this command on a binary file.

See also

ls

diff

Purpose

Show differences in the working tree, between revisions or branches.

Usage

bzr diff [FILE...]

Options

--stat Show diff summary statistics
--old=ARG Branch/tree to compare from.
-v, --verbose Display more information.
--stat-dir Show diff summary statistics per directory
-q, --quiet Only display errors and warnings.
-p ARG, --prefix=ARG
 Set prefixes added to old and new filenames, as two values separated by a colon. (eg “old/:new/”).
--using=ARG Use this command to compare files.
--usage Show usage message and options.
--new=ARG Branch/tree to compare to.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
--diff-options=ARG
 Pass these options to the external diff program.
-c ARG, --change=ARG
 Select changes introduced by the specified revision. See also “help revisionspec”.
-h, --help Show help message.

Description

If no arguments are given, all changes for the current tree are listed. If files are given, only the changes in those files are listed. Remote and multiple branches can be compared by using the –old and –new options. If not provided, the default for both is derived from the first argument, if any, or the current tree if no arguments are given.

“bzr diff -p1” is equivalent to “bzr diff –prefix old/:new/”, and produces patches suitable for “patch -p1”.

Exit values

1 - changed 2 - unrepresentable changes 3 - error 0 - no change

Examples

Shows the difference in the working tree versus the last commit:

bzr diff

Difference between the working tree and revision 1:

bzr diff -r1

Difference between revision 2 and revision 1:

bzr diff -r1..2

Difference between revision 2 and revision 1 for branch xxx:

bzr diff -r1..2 xxx

Show just the differences for file NEWS:

bzr diff NEWS

Show the differences in working tree xxx for file NEWS:

bzr diff xxx/NEWS

Show the differences from branch xxx to this working tree:

bzr diff –old xxx

Show the differences between two branches for file NEWS:

bzr diff --old xxx --new yyy NEWS

Same as ‘bzr diff’ but prefix paths with old/ and new/:

bzr diff --prefix old/:new/

Aliases

di, dif

See also

status

help

Purpose

Show help on a command or other topic.

Usage

bzr help [TOPIC]

Options

--usage Show usage message and options.
-v, --verbose Display more information.
-q, --quiet Only display errors and warnings.
--long Show help on all commands.
-h, --help Show help message.

Aliases

?, –help, -?, -h

See also

topics

log

Purpose

Show historical log for a branch or subset of a branch.

Usage

bzr log [FILE...]

Options

-v, --verbose Show files changed in each revision.
-q, --quiet Only display errors and warnings.
--include-merges
 Show merged revisions like –levels 0 does.
-p, --show-diff
 Show changes made in each revision as a patch.
--forward Show from oldest to newest.
-n N, --levels=N
 Number of levels to display - 0 for all, 1 for flat.
-l N, --limit=N
 Limit the output to the first N revisions.
--usage Show usage message and options.
--timezone=ARG Display timezone as local, original, or utc.
--show-ids Show internal object ids.
-r ARG, --revision=ARG
 See “help revisionspec” for details.
-m ARG, --message=ARG
 Show revisions whose message matches this regular expression.
-c ARG, --change=ARG
 Show just the specified revision. See also “help revisionspec”.
-h, --help Show help message.
Log format:
--log-format=ARG
 Use specified log format.
--git Git-like log format
--gnu-changelog
 Format used by GNU ChangeLog files
--line Log format with one line per revision
--long Detailed log format
--short Moderately short log format
--xml Detailed XML log format

Description

log is bzr’s default tool for exploring the history of a branch. The branch to use is taken from the first parameter. If no parameters are given, the branch containing the working directory is logged. Here are some simple examples:

bzr log                       log the current branch
bzr log foo.py                log a file in its branch
bzr log http://server/branch  log a branch on a server

The filtering, ordering and information shown for each revision can be controlled as explained below. By default, all revisions are shown sorted (topologically) so that newer revisions appear before older ones and descendants always appear before ancestors. If displayed, merged revisions are shown indented under the revision in which they were merged.

Output control

The log format controls how information about each revision is displayed. The standard log formats are called long, short and line. The default is long. See bzr help log-formats for more details on log formats.

The following options can be used to control what information is displayed:

-l N        display a maximum of N revisions
-n N        display N levels of revisions (0 for all, 1 for collapsed)
-v          display a status summary (delta) for each revision
-p          display a diff (patch) for each revision
--show-ids  display revision-ids (and file-ids), not just revnos

Note that the default number of levels to display is a function of the log format. If the -n option is not used, the standard log formats show just the top level (mainline).

Status summaries are shown using status flags like A, M, etc. To see the changes explained using words like added and modified instead, use the -vv option.

Ordering control

To display revisions from oldest to newest, use the –forward option. In most cases, using this option will have little impact on the total time taken to produce a log, though –forward does not incrementally display revisions like –reverse does when it can.

Revision filtering

The -r option can be used to specify what revision or range of revisions to filter against. The various forms are shown below:

-rX      display revision X
-rX..    display revision X and later
-r..Y    display up to and including revision Y
-rX..Y   display from X to Y inclusive

See bzr help revisionspec for details on how to specify X and Y. Some common examples are given below:

-r-1                show just the tip
-r-10..             show the last 10 mainline revisions
-rsubmit:..         show what's new on this branch
-rancestor:path..   show changes since the common ancestor of this
                    branch and the one at location path
-rdate:yesterday..  show changes since yesterday

When logging a range of revisions using -rX..Y, log starts at revision Y and searches back in history through the primary (“left-hand”) parents until it finds X. When logging just the top level (using -n1), an error is reported if X is not found along the way. If multi-level logging is used (-n0), X may be a nested merge revision and the log will be truncated accordingly.

Path filtering

If parameters are given and the first one is not a branch, the log will be filtered to show only those revisions that changed the nominated files or directories.

Filenames are interpreted within their historical context. To log a deleted file, specify a revision range so that the file existed at the end or start of the range.

Historical context is also important when interpreting pathnames of renamed files/directories. Consider the following example:

  • revision 1: add tutorial.txt
  • revision 2: modify tutorial.txt
  • revision 3: rename tutorial.txt to guide.txt; add tutorial.txt

In this case:

  • bzr log guide.txt will log the file added in revision 1
  • bzr log tutorial.txt will log the new file added in revision 3
  • bzr log -r2 -p tutorial.txt will show the changes made to the original file in revision 2.
  • bzr log -r2 -p guide.txt will display an error message as there was no file called guide.txt in revision 2.

Renames are always followed by log. By design, there is no need to explicitly ask for this (and no way to stop logging a file back until it was last renamed).

Other filtering

The –message option can be used for finding revisions that match a regular expression in a commit message.

Tips & tricks

GUI tools and IDEs are often better at exploring history than command line tools. You may prefer qlog or glog from the QBzr and Bzr-Gtk packages respectively for example. (TortoiseBzr uses qlog for displaying logs.) See http://bazaar-vcs.org/BzrPlugins and http://bazaar-vcs.org/IDEIntegration.

Web interfaces are often better at exploring history than command line tools, particularly for branches on servers. You may prefer Loggerhead or one of its alternatives. See http://bazaar-vcs.org/WebInterface.

You may find it useful to add the aliases below to bazaar.conf:

[ALIASES]
tip = log -r-1
top = log -l10 --line
show = log -v -p

bzr tip will then show the latest revision while bzr top will show the last 10 mainline revisions. To see the details of a particular revision X, bzr show -rX.

If you are interested in looking deeper into a particular merge X, use bzr log -n0 -rX.

bzr log -v on a branch with lots of history is currently very slow. A fix for this issue is currently under development. With or without that fix, it is recommended that a revision range be given when using the -v option.

bzr has a generic full-text matching plugin, bzr-search, that can be used to find revisions matching user names, commit messages, etc. Among other features, this plugin can find all revisions containing a list of words but not others.

When exploring non-mainline history on large projects with deep history, the performance of log can be greatly improved by installing the historycache plugin. This plugin buffers historical information trading disk space for faster speed.

See also

log-formats, revisionspec

status

Purpose

Display status summary.

Usage

bzr status [FILE...]

Options

-S, --short Use short status indicators.
-v, --verbose Display more information.
-V, --versioned
 Only show versioned files.
--no-pending Don’t show pending merges.
-h, --help Show help message.
-q, --quiet Only display errors and warnings.
--usage Show usage message and options.
--show-ids Show internal object ids.
-c ARG, --change=ARG
 Select changes introduced by the specified revision. See also “help revisionspec”.
-r ARG, --revision=ARG
 See “help revisionspec” for details.

Description

This reports on versioned and unknown files, reporting them grouped by state. Possible states are:

added
Versioned in the working copy but not in the previous revision.
removed
Versioned in the previous revision but removed or deleted in the working copy.
renamed
Path of this file changed from the previous revision; the text may also have changed. This includes files whose parent directory was renamed.
modified
Text has changed since the previous revision.
kind changed
File kind has been changed (e.g. from file to directory).
unknown
Not versioned and not matching an ignore pattern.

To see ignored files use ‘bzr ignored’. For details on the changes to file texts, use ‘bzr diff’.

Note that –short or -S gives status flags for each item, similar to Subversion’s status command. To get output similar to svn -q, use bzr status -SV.

If no arguments are specified, the status of the entire working directory is shown. Otherwise, only the status of the specified files or directories is reported. If a directory is given, status is reported for everything inside that directory.

Before merges are committed, the pending merge tip revisions are shown. To see all pending merge revisions, use the -v option. To skip the display of pending merge information altogether, use the no-pending option or specify a file/directory.

If a revision argument is given, the status is calculated against that revision, or between two revisions if two are provided.

Aliases

st, stat

See also

diff, revert, status-flags