API docs for “bzrlib.log”

Code to show logs of changes.

Various flavors of log can be produced:

for one file, or the whole tree, and (not done yet) for files in a given directory
in "verbose" mode with a description of what changed from one version to the next
with file-ids and revision-ids shown

Logs are actually written out through an abstract LogFormatter interface, which allows for different preferred formats. Plugins can register formats too.

Logs can be produced in either forward (oldest->newest) or reverse (newest->oldest) order.

Logs can be filtered to show only revisions matching a particular search string, or within a particular range of revisions. The range can be given as date/times, which are reduced to revisions before calling in here.

In verbose mode we show a summary of what changed in each particular revision. Note that this is the delta for changes in that revision relative to its left-most parent, not the delta relative to the last logged revision. So for example if you ask for a verbose log of changes touching hello.c you will get a list of those revisions also listing other things that were changed in the same revision, but not all the changes since the previous revision that touched hello.c.

Line #	Kind	Name	Docs
89	Function	find_touching_revisions	Yield a description of revisions which affect the file_id.
142	Function	show_log	Write out human-readable log of commits to this branch.
246	Function	calculate_view_revisions	Undocumented
517	Function	get_view_revisions	Produce an iterator of revisions to show
556	Function	reverse_by_depth	Reverse revisions by depth.
579	Class	LogRevision	A revision to be logged (by LogFormatter.log_revision).
596	Class	LogFormatter	Abstract class to display log messages.
648	Class	LongLogFormatter	No class docstring; 1/1 methods documented
694	Class	ShortLogFormatter	Undocumented
730	Class	LineLogFormatter	No class docstring; 1/6 methods documented
777	Function	line_log	Undocumented
782	Class	LogFormatterRegistry	Registry for log formatters
808	Function	register_formatter	Undocumented
812	Function	log_formatter	Construct a formatter from arguments.
824	Function	show_one_log	Undocumented
830	Function	show_changed_revisions	Show the change in revision history comparing the old revision history to the new one.
133	Function	_enumerate_history	Undocumented
193	Function	_show_log	Worker function for show_log - see show_log.
293	Function	_linear_view_revisions	Undocumented
301	Function	_iter_revisions	Undocumented
321	Function	_get_mainline_revs	Get the mainline revisions from the branch.
403	Function	_filter_revision_range	Filter view_revisions based on revision ranges.
446	Function	_filter_revisions_touching_file_id	Return the list of revision ids which touch a given file id.

def find_touching_revisions(branch, file_id):

Yield a description of revisions which affect the file_id.

Each returned element is (revno, revision_id, description)

This is the list of revisions where the file is either added, modified, renamed or deleted.

TODO: Perhaps some way to limit this to only particular revisions, or to traverse a non-mainline set of revisions?

def show_log(branch, lf, specific_fileid=None, verbose=False, direction='reverse', start_revision=None, end_revision=None, search=None, limit=None):

Write out human-readable log of commits to this branch.

lf: LogFormatter object to show the output.
specific_fileid: If true, list only the commits affecting the specified file, rather than all commits.
verbose: If true show added/changed/deleted/renamed files.
direction: 'reverse' (default) is latest to earliest; 'forward' is earliest to latest.
start_revision: If not None, only show revisions >= start_revision
end_revision: If not None, only show revisions <= end_revision
search: If not None, only show revisions with matching commit messages
limit: If not None or 0, only show limit revisions

def _get_mainline_revs(branch, start_revision, end_revision):

Get the mainline revisions from the branch.

Generates the list of mainline revisions for the branch.

Parameters	branch	The branch containing the revisions.
	start_revision	The first revision to be logged. For backwards compatibility this may be a mainline integer revno, but for merge revision support a RevisionInfo is expected.
	end_revision	The last revision to be logged. For backwards compatibility this may be a mainline integer revno, but for merge revision support a RevisionInfo is expected.
Returns	A (mainline_revs, rev_nos, start_rev_id, end_rev_id) tuple.

def _filter_revision_range(view_revisions, start_rev_id, end_rev_id):

Filter view_revisions based on revision ranges.

Parameters	view_revisions	A list of (revision_id, dotted_revno, merge_depth) tuples to be filtered.
	start_rev_id	If not NONE specifies the first revision to be logged. If NONE then all revisions up to the end_rev_id are logged.
	end_rev_id	If not NONE specifies the last revision to be logged. If NONE then all revisions up to the end of the log are logged.
Returns	The filtered view_revisions.

def _filter_revisions_touching_file_id(branch, file_id, mainline_revisions, view_revs_iter):

Return the list of revision ids which touch a given file id.

The function filters view_revisions and returns a subset.
This includes the revisions which directly change the file id,
and the revisions which merge these changes. So if the
revision graph is::
    A
    |        B C
    |/
    D

And 'C' changes a file, then both C and D will be returned.

This will also can be restricted based on a subset of the mainline.

:return: A list of (revision_id, dotted_revno, merge_depth) tuples.

def reverse_by_depth(merge_sorted_revisions, _depth=0):

Reverse revisions by depth.

Revisions with a different depth are sorted as a group with the previous revision of that depth. There may be no topological justification for this, but it looks much nicer.

def show_changed_revisions(branch, old_rh, new_rh, to_file=None, log_format='long'):

Show the change in revision history comparing the old revision history to the new one.

Parameters	branch	The branch where the revisions exist
	old_rh	The old revision history
	new_rh	The new revision history
	to_file	A file to write the results to. If None, stdout will be used

Module b.log