b.log : module documentation

Part of bzrlib

Code to show logs of changes.

Various flavors of log can be produced:

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.

ParameterslfThe LogFormatter object showing the output.
specific_fileidIf not None, list only the commits affecting the specified file, rather than all commits.
verboseIf True show added/changed/deleted/renamed files.
direction'reverse' (default) is latest to earliest; 'forward' is earliest to latest.
start_revisionIf not None, only show revisions >= start_revision
end_revisionIf not None, only show revisions <= end_revision
searchIf not None, only show revisions with matching commit messages
limitIf set, shows only 'limit' revisions, all revisions are shown if None or 0.
show_diffIf True, output a diff after each revision.
matchDictionary 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
Parametersrev_idrevision id to validate
reporepository of revision
Returnshuman 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.
ReturnsAn 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.
ReturnsThe 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.
Parametersstart_rev_idthe lower revision-id
end_rev_idthe upper revision-id
exclude_common_ancestryWhether the start_rev_id should be part of the iterated revisions.
ReturnsAn iterator of (revision_id, dotted_revno, merge_depth) tuples.
Raises_StartNotLinearAncestorif 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.
Parametersbranchthe branch
start_rev_idthe lower revision-id
end_rev_idthe upper revision-id
rebase_initial_depthshould depths be rebased until a mainline revision is found?
ReturnsAn 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.
ParametersbranchThe branch being logged.
view_revisionsThe revisions being viewed.
generate_deltaWhether to generate a delta for each revision. Permitted values are None, 'full' and 'partial'.
searchA user text search string.
file_idsIf non empty, only revisions matching one or more of the file-ids are to be kept.
directionthe direction in which view_revisions is sorted
ReturnsAn 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.
ParametersbranchThe branch being logged.
generate_deltaWhether to generate a delta for each revision.
matchA 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_iteratorAn input iterator containing all revisions that could be displayed, in lists.
ReturnsAn 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.
ParametersbranchThe branch being logged.
generate_deltaWhether to generate a delta for each revision. Permitted values are None, 'full' and 'partial'.
searchA user text search string.
log_rev_iteratorAn input iterator containing all revisions that could be displayed, in lists.
fileidsIf non empty, only revisions matching one or more of the file-ids are to be kept.
directionthe direction in which view_revisions is sorted
ReturnsAn 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.
Parametersfileidsa set of fileids to update
stop_oneither '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
ParametersbranchThe branch being logged.
generate_deltaWhether to generate a delta for each revision.
searchA user text search string.
log_rev_iteratorAn input iterator containing all revisions that could be displayed, in lists.
ReturnsAn 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.
ParametersbranchThe branch being logged.
generate_deltaWhether to generate a delta for each revision.
searchA user text search string.
log_rev_iteratorAn input iterator containing all revisions that could be displayed, in lists.
ReturnsAn 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.
ParametersbranchThe branch containing the revisions.
start_revisionThe 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_revisionThe 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.

ParametersbranchThe branch containing the revisions.
start_revisionThe 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_revisionThe last revision to be logged. For backwards compatibility this may be a mainline integer revno, but for merge revision support a RevisionInfo is expected.
ReturnsA (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.

ParametersbranchThe branch where we can get text revision information.
file_idFilter out revisions that do not touch file_id.
view_revisionsA 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_mergesinclude merge revisions in the result or not
ReturnsA 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.
ParametersbranchThe branch where the revisions exist
old_rhThe old revision history
new_rhThe new revision history
to_fileA 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

Parametersold_revision_idThe original revision id.
new_revision_idThe new revision id.
repositoryThe repository to use for the calculation.
def show_branch_change(branch, output, old_revno, old_revision_id):
Show the changes made to a branch.
ParametersbranchThe branch to show changes about.
outputA file-like object to write changes to.
old_revnoThe revno of the old tip.
old_revision_idThe revision_id of the old tip.
def show_flat_log(repository, history, last_revno, lf):
Show a simple log of the specified history.
ParametersrepositoryThe repository to retrieve revisions from.
historyA list of revision_ids indicating the lefthand history.
last_revnoThe revno of the last revision_id in the history.
lfThe 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.

Parametersrevisionspec_listrevision range as parsed on the command line
file_listthe 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_cleanupWhen 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 2019-07-19 00:30:15.