b.log : module documentation

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.

Function	find_touching_revisions	Yield a description of revisions which affect the file_id.
Function	show_log	Write out human-readable log of commits to this branch.
Function	make_log_request_dict	Convenience function for making a logging request dictionary.
Function	format_signature_validity	get the signature validity
Class	LogGenerator	A generator of log revisions.
Class	Logger	An object that generates, formats and displays a log.
Function	make_log_rev_iterator	Create a revision iterator for log.
Function	reverse_by_depth	Reverse revisions by depth.
Class	LogRevision	A revision to be logged (by LogFormatter.log_revision).
Class	LogFormatter	Abstract class to display log messages.
Class	LongLogFormatter	No class docstring; 2/5 methods documented
Class	ShortLogFormatter	Undocumented
Class	LineLogFormatter	No class docstring; 1/6 methods documented
Class	GnuChangelogLogFormatter	No class docstring; 1/1 methods documented
Function	line_log	Undocumented
Class	LogFormatterRegistry	Registry for log formatters
Function	register_formatter	Undocumented
Function	log_formatter	Construct a formatter from arguments.
Function	author_list_all	Undocumented
Function	author_list_first	Undocumented
Function	author_list_committer	Undocumented
Function	show_changed_revisions	Show the change in revision history comparing the old revision history to the new one.
Function	get_history_change	Calculate the uncommon lefthand history between two revisions.
Function	show_branch_change	Show the changes made to a branch.
Function	show_flat_log	Show a simple log of the specified history.
Function	_enumerate_history	Undocumented
Function	_apply_log_request_defaults	Apply default values to a request dictionary.
Class	_StartNotLinearAncestor	Raised when a start revision is not found walking left-hand history.
Class	_DefaultLogGenerator	The default generator of log revisions.
Function	_calc_view_revisions	Calculate the revisions to view.
Function	_generate_one_revision	Undocumented
Function	_generate_flat_revisions	Undocumented
Function	_generate_all_revisions	Undocumented
Function	_has_merges	Does a revision have multiple parents or not?
Function	_compute_revno_str	Compute the revno string from a rev_id.
Function	_is_obvious_ancestor	Is start_rev_id an obvious ancestor of end_rev_id?
Function	_linear_view_revisions	Calculate a sequence of revisions to view, newest to oldest.
Function	_graph_view_revisions	Calculate revisions to view including merges, newest to oldest.
Function	_rebase_merge_depth	Adjust depths upwards so the top level is 0.
Function	_make_search_filter	Create a filtered iterator of log_rev_iterator matching on a regex.
Function	_filter_re	Undocumented
Function	_match_filter	Undocumented
Function	_match_any_filter	Undocumented
Function	_make_delta_filter	Add revision deltas to a log iterator if needed.
Function	_generate_deltas	Create deltas for each batch of revisions in log_rev_iterator.
Function	_update_fileids	Update the set of file-ids to search based on file lifecycle events.
Function	_make_revision_objects	Extract revision objects from the repository
Function	_make_batch_filter	Group up a single large batch into smaller ones.
Function	_get_revision_limits	Get and check revision limits.
Function	_get_mainline_revs	Get the mainline revisions from the branch.
Function	_filter_revisions_touching_file_id	Return the list of revision ids which touch a given file id.
Function	_get_info_for_log_files	Find file-ids and kinds given a list of files and a revision range.
Function	_get_kind_for_file_id	Return the kind of a file-id or None if it doesn't exist.
Function	_bugs_properties_handler	Undocumented

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 _enumerate_history(branch):

Undocumented

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

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

This function is being retained for backwards compatibility but should not be extended with new parameters. Use the new Logger class instead, eg. Logger(branch, rqst).show(lf), adding parameters to the make_log_request_dict function.

Parameters	lf	The LogFormatter object showing the output.
	specific_fileid	If not None, 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 set, shows only 'limit' revisions, all revisions are shown if None or 0.
	show_diff	If True, output a diff after each revision.
	match	Dictionary of search lists to use when matching revision properties.

def make_log_request_dict(direction='reverse', specific_fileids=None, start_revision=None, end_revision=None, limit=None, message_search=None, levels=None, generate_tags=True, delta_type=None, diff_type=None, _match_using_deltas=True, exclude_common_ancestry=False, match=None, signature=False, omit_merges=False):

Convenience function for making a logging request dictionary.

    Using this function may make code slightly safer by ensuring
    parameters have the correct names. It also provides a reference
    point for documenting the supported parameters.

    :param direction: 'reverse' (default) is latest to earliest;
      'forward' is earliest to latest.

    :param specific_fileids: If not None, only include revisions
      affecting the specified files, rather than all revisions.

    :param start_revision: If not None, only generate
      revisions >= start_revision

    :param end_revision: If not None, only generate
      revisions <= end_revision

    :param limit: If set, generate only 'limit' revisions, all revisions
      are shown if None or 0.

    :param message_search: If not None, only include revisions with
      matching commit messages

    :param levels: the number of levels of revisions to
      generate; 1 for just the mainline; 0 for all levels, or None for
      a sensible default.

    :param generate_tags: If True, include tags for matched revisions.
`
    :param delta_type: Either 'full', 'partial' or None.
      'full' means generate the complete delta - adds/deletes/modifies/etc;
      'partial' means filter the delta using specific_fileids;
      None means do not generate any delta.

    :param diff_type: Either 'full', 'partial' or None.
      'full' means generate the complete diff - adds/deletes/modifies/etc;
      'partial' means filter the diff using specific_fileids;
      None means do not generate any diff.

    :param _match_using_deltas: a private parameter controlling the
      algorithm used for matching specific_fileids. This parameter
      may be removed in the future so bzrlib client code should NOT
      use it.

    :param exclude_common_ancestry: Whether -rX..Y should be interpreted as a
      range operator or as a graph difference.

    :param signature: show digital signature information

    :param match: Dictionary of list of search strings to use when filtering
      revisions. Keys can be 'message', 'author', 'committer', 'bugs' or
      the empty string to match any of the preceding properties.

    :param omit_merges: If True, commits with more than one parent are
      omitted.

def _apply_log_request_defaults(rqst):

Apply default values to a request dictionary.

def format_signature_validity(rev_id, repo):

get the signature validity

Parameters	rev_id	revision id to validate
	repo	repository of revision
Returns	human readable string to print to log

def _calc_view_revisions(branch, start_rev_id, end_rev_id, direction, generate_merge_revisions, delayed_graph_generation=False, exclude_common_ancestry=False):

Calculate the revisions to view.

Returns An iterator of (revision_id, dotted_revno, merge_depth) tuples OR a list of the same tuples.

def _generate_one_revision(branch, rev_id, br_rev_id, br_revno):

Undocumented

def _generate_flat_revisions(branch, start_rev_id, end_rev_id, direction, exclude_common_ancestry=False):

Undocumented

def _generate_all_revisions(branch, start_rev_id, end_rev_id, direction, delayed_graph_generation, exclude_common_ancestry=False):

Undocumented

def _has_merges(branch, rev_id):

Does a revision have multiple parents or not?

def _compute_revno_str(branch, rev_id):

Compute the revno string from a rev_id.

Returns The revno string, or None if the revision is not in the supplied branch.

def _is_obvious_ancestor(branch, start_rev_id, end_rev_id):

Is start_rev_id an obvious ancestor of end_rev_id?

def _linear_view_revisions(branch, start_rev_id, end_rev_id, exclude_common_ancestry=False):

Calculate a sequence of revisions to view, newest to oldest.

Parameters	start_rev_id	the lower revision-id
	end_rev_id	the upper revision-id
	exclude_common_ancestry	Whether the start_rev_id should be part of the iterated revisions.
Returns	An iterator of (revision_id, dotted_revno, merge_depth) tuples.
Raises	_StartNotLinearAncestor	if a start_rev_id is specified but is not found walking the left-hand history

def _graph_view_revisions(branch, start_rev_id, end_rev_id, rebase_initial_depths=True, exclude_common_ancestry=False):

Calculate revisions to view including merges, newest to oldest.

Parameters	branch	the branch
	start_rev_id	the lower revision-id
	end_rev_id	the upper revision-id
	rebase_initial_depth	should depths be rebased until a mainline revision is found?
Returns	An iterator of (revision_id, dotted_revno, merge_depth) tuples.

def _rebase_merge_depth(view_revisions):

Adjust depths upwards so the top level is 0.

def make_log_rev_iterator(branch, view_revisions, generate_delta, search, file_ids=None, direction='reverse'):

Create a revision iterator for log.

Parameters	branch	The branch being logged.
	view_revisions	The revisions being viewed.
	generate_delta	Whether to generate a delta for each revision. Permitted values are None, 'full' and 'partial'.
	search	A user text search string.
	file_ids	If non empty, only revisions matching one or more of the file-ids are to be kept.
	direction	the direction in which view_revisions is sorted
Returns	An iterator over lists of ((rev_id, revno, merge_depth), rev, delta).

def _make_search_filter(branch, generate_delta, match, log_rev_iterator):

Create a filtered iterator of log_rev_iterator matching on a regex.

Parameters	branch	The branch being logged.
	generate_delta	Whether to generate a delta for each revision.
	match	A dictionary with properties as keys and lists of strings as values. To match, a revision may match any of the supplied strings within a single property but must match at least one string for each property.
	log_rev_iterator	An input iterator containing all revisions that could be displayed, in lists.
Returns	An iterator over lists of ((rev_id, revno, merge_depth), rev, delta).

def _filter_re(searchRE, log_rev_iterator):

Undocumented

def _match_filter(searchRE, rev):

Undocumented

def _match_any_filter(strings, res):

Undocumented

def _make_delta_filter(branch, generate_delta, search, log_rev_iterator, fileids=None, direction='reverse'):

Add revision deltas to a log iterator if needed.

Parameters	branch	The branch being logged.
	generate_delta	Whether to generate a delta for each revision. Permitted values are None, 'full' and 'partial'.
	search	A user text search string.
	log_rev_iterator	An input iterator containing all revisions that could be displayed, in lists.
	fileids	If non empty, only revisions matching one or more of the file-ids are to be kept.
	direction	the direction in which view_revisions is sorted
Returns	An iterator over lists of ((rev_id, revno, merge_depth), rev, delta).

def _generate_deltas(repository, log_rev_iterator, delta_type, fileids, direction):

Create deltas for each batch of revisions in log_rev_iterator.

If we're only generating deltas for the sake of filtering against file-ids, we stop generating deltas once all file-ids reach the appropriate life-cycle point. If we're receiving data newest to oldest, then that life-cycle point is 'add', otherwise it's 'remove'.

def _update_fileids(delta, fileids, stop_on):

Update the set of file-ids to search based on file lifecycle events.

Parameters	fileids	a set of fileids to update
	stop_on	either 'add' or 'remove' - take file-ids out of the fileids set once their add or remove entry is detected respectively

def _make_revision_objects(branch, generate_delta, search, log_rev_iterator):

Extract revision objects from the repository

Parameters	branch	The branch being logged.
	generate_delta	Whether to generate a delta for each revision.
	search	A user text search string.
	log_rev_iterator	An input iterator containing all revisions that could be displayed, in lists.
Returns	An iterator over lists of ((rev_id, revno, merge_depth), rev, delta).

def _make_batch_filter(branch, generate_delta, search, log_rev_iterator):

Group up a single large batch into smaller ones.

Parameters	branch	The branch being logged.
	generate_delta	Whether to generate a delta for each revision.
	search	A user text search string.
	log_rev_iterator	An input iterator containing all revisions that could be displayed, in lists.
Returns	An iterator over lists of ((rev_id, revno, merge_depth), rev, delta).

def _get_revision_limits(branch, start_revision, end_revision):

Get and check revision limits.

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	(start_rev_id, end_rev_id) tuple.

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_revisions_touching_file_id(branch, file_id, view_revisions, include_merges=True):

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 E
|/ /
D |
|\|
| F
|/
G

And 'C' changes a file, then both C and D will be returned. F will not be returned even though it brings the changes to C into the branch starting with E. (Note that if we were using F as the tip instead of G, then we would see C, D, F.)

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

Parameters	branch	The branch where we can get text revision information.
	file_id	Filter out revisions that do not touch file_id.
	view_revisions	A list of (revision_id, dotted_revno, merge_depth) tuples. This is the list of revisions which will be filtered. It is assumed that view_revisions is in merge_sort order (i.e. newest revision first ).
	include_merges	include merge revisions in the result or not
Returns	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 line_log(rev, max_chars):

Undocumented

def register_formatter(name, formatter):

Undocumented

def log_formatter(name, *args, **kwargs):

Construct a formatter from arguments.

name -- Name of the formatter to construct; currently 'long', 'short' and: 'line' are supported.

def author_list_all(rev):

Undocumented

def author_list_first(rev):

Undocumented

def author_list_committer(rev):

Undocumented

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

def get_history_change(old_revision_id, new_revision_id, repository):

Calculate the uncommon lefthand history between two revisions.

return old_history, new_history

Parameters	old_revision_id	The original revision id.
	new_revision_id	The new revision id.
	repository	The repository to use for the calculation.

def show_branch_change(branch, output, old_revno, old_revision_id):

Show the changes made to a branch.

Parameters	branch	The branch to show changes about.
	output	A file-like object to write changes to.
	old_revno	The revno of the old tip.
	old_revision_id	The revision_id of the old tip.

def show_flat_log(repository, history, last_revno, lf):

Show a simple log of the specified history.

Parameters	repository	The repository to retrieve revisions from.
	history	A list of revision_ids indicating the lefthand history.
	last_revno	The revno of the last revision_id in the history.
	lf	The log formatter to use.

def _get_info_for_log_files(revisionspec_list, file_list, add_cleanup):

Find file-ids and kinds given a list of files and a revision range.

We search for files at the end of the range. If not found there, we try the start of the range.

Parameters	revisionspec_list	revision range as parsed on the command line
	file_list	the list of paths given on the command line; the first of these can be a branch location or a file path, the remainder must be file paths
	add_cleanup	When the branch returned is read locked, an unlock call will be queued to the cleanup.
Returns	(branch, info_list, start_rev_info, end_rev_info) where info_list is a list of (relative_path, file_id, kind) tuples where kind is one of values 'directory', 'file', 'symlink', 'tree-reference'. branch will be read-locked.

def _get_kind_for_file_id(tree, file_id):

Return the kind of a file-id or None if it doesn't exist.

def _bugs_properties_handler(revision):

Undocumented

API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.