.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Arch::Tree 3pm"
.TH Arch::Tree 3pm "2022-06-08" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Arch::Tree \- class representing Arch tree
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Arch::Tree;
\&    my $tree = Arch::Tree\->new;  # assume the current dir
\&
\&    print map { "$_\en" } $tree\->get_log_versions;
\&
\&    foreach my $log ($tree\->get_logs) {
\&        print "\-" x 80, "\en";
\&        print $log\->standard_date, "\en";
\&        print $log\->summary, "\en\en";
\&        print $log\->body;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents the working tree concept in Arch and provides some
useful methods.
.SH "METHODS"
.IX Header "METHODS"
The following methods are available:
.PP
\&\fBnew\fR,
\&\fBroot\fR,
\&\fBget_version\fR,
\&\fBset_version\fR,
\&\fBget_log_versions\fR,
\&\fBadd_log_version\fR,
\&\fBget_log_revisions\fR,
\&\fBget_log\fR,
\&\fBget_logs\fR,
\&\fBget_log_revision_descs\fR,
\&\fBget_inventory\fR,
\&\fBget_changes\fR,
\&\fBget_changeset\fR,
\&\fBget_merged_log_text\fR,
\&\fBget_merged_revision_summaries\fR,
\&\fBget_merged_revisions\fR,
\&\fBget_missing_revisions\fR,
\&\fBget_missing_revision_descs\fR,
\&\fBget_previous_revision\fR,
\&\fBget_ancestry_logs\fR,
\&\fBget_history_revision_descs\fR,
\&\fBget_annotate_revision_descs\fR,
\&\fBclear_cache\fR,
\&\fBadd\fR,
\&\fBdelete\fR,
\&\fBmode\fR,
\&\fBget_file_diff\fR,
\&\fBmake_log\fR,
\&\fBimport\fR,
\&\fBcommit\fR.
.IP "\fBnew\fR [\fIdir-name\fR]" 4
.IX Item "new [dir-name]"
Construct the Arch::Tree object associated with the existing directory
\&\fIdir-name\fR. The default is the current '.' directory.
.IP "\fBroot\fR" 4
.IX Item "root"
Returns the project tree root.
.IP "\fBget_version\fR" 4
.IX Item "get_version"
Returns the fully qualified tree version.
.IP "\fBget_revision\fR" 4
.IX Item "get_revision"
Returns the fully qualified tree revision.
.IP "\fBset_version\fR \fIversion\fR" 4
.IX Item "set_version version"
Changes the tree version to \fIversion\fR.
.IP "\fBget_log_versions\fR" 4
.IX Item "get_log_versions"
Returns all version names (including the main one and merged ones) for which
logs are stored in the tree. In the scalar context returns arrayref.
.IP "\fBadd_log_version\fR \fIversion\fR" 4
.IX Item "add_log_version version"
Add log version \fIversion\fR to project tree.
.IP "\fBget_log_revisions\fR [\fIversion\fR]" 4
.IX Item "get_log_revisions [version]"
Returns all revision names of the given \fIversion\fR (the default is the tree
version) for which logs are stored in the tree. In the scalar context
returns arrayref.
.IP "\fBget_log\fR \fIrevision\fR" 4
.IX Item "get_log revision"
Return Arch::Log object corresponding to the tree log of the given \fIrevision\fR.
.IP "\fBget_logs\fR [\fIversion\fR]" 4
.IX Item "get_logs [version]"
Return Arch::Log objects corresponding to the tree logs of the given \fIversion\fR.
In the scalar context returns arrayref.
.Sp
The default \fIversion\fR is the tree version (see \f(CW\*(C`get_version\*(C'\fR).
A special version name '*' may be used, in this case all logs in
\&\f(CW\*(C`get_log_versions\*(C'\fR are returned. \fIversion\fR may be arrayref as well
with the similar results.
.IP "\fBget_log_revision_descs\fR [\fIversion\fR]" 4
.IX Item "get_log_revision_descs [version]"
Returns arrayref of log revision description hashes corresponding to
\&\fIversion\fR. The optional \fIversion\fR argument may get the same values that
are supported by \fBget_logs\fR.
.IP "\fBget_inventory\fR" 4
.IX Item "get_inventory"
Returns Arch::Inventory object for the project tree.
.IP "\fBget_changes\fR" 4
.IX Item "get_changes"
Returns a list of uncommited changes in the project tree.
.IP "\fBget_changeset\fR \fIdir\fR" 4
.IX Item "get_changeset dir"
Creates an \fBArch::Changeset\fR of the uncommited changes in the
tree. The directory \fIdir\fR is used to store the changeset and must not
already exist. It will not be automatically removed.
.IP "\fBget_merged_log_text\fR" 4
.IX Item "get_merged_log_text"
This is just the output of \*(L"tla log-for-merge\*(R".
.IP "\fBget_merged_revision_summaries\fR" 4
.IX Item "get_merged_revision_summaries"
Returns hash (actually sorted array of pairs) or hashref in the scalar
context. The pair is for every merged revision: full-name => summary.
.IP "\fBget_merged_revisions\fR" 4
.IX Item "get_merged_revisions"
The list of all merged in (present in the changes) full revisions.
In the scalar context returns arrayref.
.IP "\fBget_missing_revisions\fR [\fIversion\fR]" 4
.IX Item "get_missing_revisions [version]"
The list of all missing revisions corresponding to \fIversion\fR.
In the scalar context returns arrayref.
.Sp
The default \fIversion\fR is the tree version (see \f(CW\*(C`get_version\*(C'\fR).
.IP "\fBget_missing_revision_descs\fR [\fIversion\fR]" 4
.IX Item "get_missing_revision_descs [version]"
The hashref of all missing revision descriptions corresponding to \fIversion\fR.
The hash keys are revisions and the values are hashrefs with keys
\&\fIname\fR, \fIsummary\fR, \fIcreator\fR, \fIemail\fR, \fIdate\fR, \fIkind\fR.
.Sp
The default \fIversion\fR is the tree version (see \f(CW\*(C`get_version\*(C'\fR).
.IP "\fBget_previous_revision\fR [<revision>]" 4
.IX Item "get_previous_revision [<revision>]"
Given the fully qualified revision name (defaulting to \fBget_revision\fR)
return the previous namespace revision in this tree version. Return undef
for the \fIbase\-0\fR revision. Note, the \fIversion\-0\fR revision argument is
handled specially.
.IP "\fBget_ancestry_logs\fR [\fI\f(CI%args\fI\fR]" 4
.IX Item "get_ancestry_logs [%args]"
Return all ancestry revision logs (calculated from the tree). The first log
in the returned arrayref corresponds to the current tree revision, the last
log is normally the original import log. If the tree has certain logs pruned
(such practice is not recommended), then such pruned log is not returned and
this method tries its best to determine its ancestor, still without
accessing the archive.
.Sp
\&\fI\f(CI%args\fI\fR accepts: flags \fIno_continuation\fR and \fIone_version\fR, and
\&\fIcallback\fR to filter a revision log before it is collected.
.Sp
If \fIno_continuation\fR is set, then do not follow tags backward.
.Sp
If \fIone_version\fR is set, then do not follow tags from the versions
different than the initial version. This is similar to \fIno_continuation\fR,
but not the same, since it is possible to tag into the same version.
.Sp
The default callback is effectivelly:
.Sp
.Vb 4
\&    sub {
\&        my ($log) = @_;
\&        return $log;
\&    }
.Ve
.Sp
Note that if the callback does \f(CW$_\fR[0] = undef among other things, this is
taken as a signal to stop processing of ancestry (the return value is still
collected even in this case; return empty list to collect nothing).
.IP "\fBget_history_revision_descs\fR [\fIfilepath\fR [\fI\f(CI%args\fI\fR]]" 4
.IX Item "get_history_revision_descs [filepath [%args]]"
Return arrayref of all ancestry revision descriptions in the backward order
(i.e. from a more recent to an older). If \fIfilepath\fR is given, then only
revisions that modified the given file (or dir) are returned. The revision
description is hashref with keys \fIname\fR, \fIsummary\fR, \fIcreator\fR, \fIemail\fR,
\&\fIdate\fR, \fIkind\fR.
.Sp
If \fIfilepath\fR if given, then the revision description hash additionally
contains keys \fIfilepath\fR, \fIorig_filepath\fR (if renamed on that revision),
\&\fIis_filepath_added\fR, \fIis_filepath_renamed\fR and \fIis_filepath_modified\fR.
.Sp
\&\fI\f(CI%args\fI\fR accepts: flags \fIno_continuation\fR and \fIone_version\fR, and
\&\fIcallback\fR to filter a revision description before it is collected.
.Sp
The default callback is effectivelly:
.Sp
.Vb 4
\&    sub {
\&        my ($revision_desc, $log) = @_;
\&        return $revision_desc;
\&    }
.Ve
.Sp
The \fI\f(CI%args\fI\fR flags and assigning to \f(CW$_\fR[0] in callback have the same meaning
as in \fBget_ancestry_logs\fR.
.IP "\fBget_annotate_revision_descs\fR [\fIfilepath\fR [\fI\f(CI%args\fI\fR]]" 4
.IX Item "get_annotate_revision_descs [filepath [%args]]"
Return file annotation data. In scalar context, returns arrayref of all
ancestry revision descriptions in the backward order (i.e. from a more
recent to an older) responsible for last modification of all file lines.
In list context, returns list of 3 values:
.Sp
.Vb 2
\&    ($lines, $line_revision_desc_indexes, $revision_descs) =
\&        $tree\->get_annotate_revision_descs($filename);
.Ve
.Sp
\&\f(CW$lines\fR is arrayref that contains all \fIfilepath\fR lines with no end-of-line;
\&\f(CW$line_revision_desc_indexes\fR is arrayref of the same length that contains
indexes to the \f(CW$revision_descs\fR arrayref. Note that \f(CW$revision_descs\fR is the
same returned in the scalar context, it is similar to the one returned by
\&\fBget_history_revision_descs\fR, but possibly contains less elements, since
some revisions only modified metadata, or only modified lines that were
modified by other revisions afterward, all such revisions are not included.
.Sp
If some lines can't be annotated (usually, because the history was cut),
then the corresonding \f(CW$line_revision_desc_indexes\fR elements are undefined.
.Sp
\&\fI\f(CI%args\fI\fR accepts: flags \fIno_continuation\fR and \fIone_version\fR, and
\&\fIcallback\fR to filter a revision description before it is collected.
.Sp
The default callback is effectivelly:
.Sp
.Vb 4
\&    sub {
\&        my ($revision_desc, $log) = @_;
\&        return $revision_desc;
\&    }
.Ve
.Sp
The \fI\f(CI%args\fI\fR flags and assigning to \f(CW$_\fR[0] in callback have the same meaning
as in \fBget_ancestry_logs\fR and \fBget_history_revision_descs\fR.
.Sp
Additionally, \fIprefetch_callback\fR is supported. If given, it is called
before fetching a changeset, with two arguments: revision, and filename to
look at the patch of which.
.Sp
More \fI\f(CI%args\fI\fR keys are \fIlinenums\fR (either string or arrayref or
hashref), \fImatch_re\fR (regular expression to filter lines). And flags
\&\fIhighlight\fR (syntax highlight lines using markup), \fIfull_history\fR
(include all file history revision even those that didn't add the current
file lines).
.IP "\fBclear_cache\fR [key ..]" 4
.IX Item "clear_cache [key ..]"
For performance reasons, some method results are cached (memoized in fact).
Use this method to explicitly request this cache to be cleared.
.Sp
By default all cached keys are cleared; \fIkey\fR may be one of the strings
\&'missing_revision_descs', 'missing_revisions'.
.IP "\fBadd\fR [{ \fIoptions\fR }] \fIfiles ...\fR" 4
.IX Item "add [{ options }] files ..."
Add exlicit inventory ids for \fIfiles\fR. A specific inventory id may be
passed via the \fIoptions\fR hash with the key \f(CW\*(C`id\*(C'\fR.
.IP "\fBdelete\fR \fIfiles ...\fR" 4
.IX Item "delete files ..."
Delete explicit inventory ids for \fIfiles\fR.
.IP "\fBmove\fR \fIold_file\fR \fInew_file\fR" 4
.IX Item "move old_file new_file"
Move exlicit file id for \fIold_file\fR to \fInew_file\fR.
.IP "\fBget_file_diff\fR \fIfile\fR" 4
.IX Item "get_file_diff file"
Get modifications for \fIfile\fR as unified diff.
.IP "\fBmake_log\fR" 4
.IX Item "make_log"
Create a new commit log, if it does not yet exist. Returns the
filename.
.IP "\fBimport\fR [{ \fIoptions\fR }] [\fIversion\fR]" 4
.IX Item "import [{ options }] [version]"
Similar to 'tla import'.
.IP "\fBcommit\fR [{ \fIoptions\fR }] [\fIversion\fR]" 4
.IX Item "commit [{ options }] [version]"
Commit changes in tree.
.Sp
Note, \fIversion\fR argument is not supported in newer baz versions.
.Sp
Optional file limits may be passed using \fIfiles\fR arrayref in \fIoptions\fR.
.SH "BUGS"
.IX Header "BUGS"
Awaiting for your reports.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.PP
Enno Cramer (uebergeek@web.de\-\-2003/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see tla, Arch::Log, Arch::Inventory,
Arch::Changes, Arch::Util, Arch::Name.