A.1 Patch Logs and Project Tree History

In the previous chapter, we began to learn about branching and merging.
We saw how commands like missing, update, and replay can be used
to keep track of and apply changes from multiple branches of a project.

In this chapter, we'll explain a bit about patch logs: the mechanism
that is used to keep track of the history of a project tree, including
that part of the history that is used for intelligent merging.

You should recall first encountering patch logs in earlier chapters
(for example, when first initializing a project tree, in
Starting a New Source Tree). In this chapter, patch logs are
explained in greater depth.

A.1.1 Project Trees Have Patch Logs

Recall that every initial import, tag revision, and changeset revision
in an archive has an associated log message. That message consists
of the headers and body that you supply to commands such as import
and commit, plus additional headers that are automatically generated
by arch.

When a project tree is first imported to an archive, the patch log
entry for the new revision is added to the tree. When a commit
takes place, as part of the process of committing, the log entry for
the new revision is added to the tree. If you get a revision
created by the tag command, you'll also find that it contains a
patch log entry for the tag revision.

Patch log entries accumulate. Thus, for example, each commit adds a
new log entry and all earlier log entries are preserved. Each tag
revision includes not only the entry for the tag, but all log entries
inherited from the revision being tagged.

Returning to our earlier examples, let's take a look at Alice and
Bob's patch-2 revision:

A.1.3 The Concept of Change History and Tree Ancestry

Patch logs give important insight into the history of a tree. There
are two views worth mentioning: the change history view, and the
tree ancestry view.

A.1.3.1 Change History

When a tree has a log for a given commit changeset, that means that
the changes from that commit have been applied to the tree: the
commit changeset is part of the "change history" of the tree. If
the changeset were a bug fix, for example, then this is a likely
indication that the bug fix is present in the tree.

Note: The mere fact that a given changeset is part of the change
history of a tree isn't absolute proof that the changes made by that
changeset are present in the tree. For example, those changes might
have been "undone" by a later change. Nevertheless, the change
history of a tree is a useful tool for exploring and understanding its
state.

A.1.4 Tree Ancestry

Informally, we say that an archived revision is a tree ancestor of a
given project tree if it has patch log entries for all of the
revisions in the version of that archived revision up to to the
archived revision itself.

Thus, for example, Candice's tag revision has Alice and Bob's
patch-1 revision as an ancestor because it has logs for Alice and
Bob's revisions:

base-0
patch-1

And Candices's patch-2 revision, which merges in changes from Alice
and Bob's patch-2 and patch-3, has both of those additional
revisions as ancestors (see Updating from a Branched-from Version in Elementary Branches – Maintaining Private Changes).

A.1.5 Automated ChangeLogs

The command tla changelog generates a GNU-style ChangeLog file from
a patch log:

Note that the generated ChangeLog includes a tagline. If you save
the output of the changelog command in a project tree, either using
tagline ids or giving it an explicit id that matches the taglines id,
the commands such as commit will automatically keep the ChangeLog up
to date.