• Tla Reference

This page should be an index of references on each tla sub-command. Commands particularly useful for new users are marked in bold, those for slightly more experienced users are in italics.

Editors: This page should be kept in sync with the output of tla help. You can use the tlahtmlref script to help with this. Sub-command pages should be kept up to date with the output of tla sub-command -H. This should be enhanced with examples, more explanation of the options, and links to related commands. See TlaCommandTemplate for the current "right" format for these pages (and feel free to edit that if you don't like it). It might be nice to include the first version of tla that each of these commands existed. A note on the direction information ought to flow:

• I'd like to ... take the wiki reference docs that we're now building, and eventually (once they've become stable) backport these to become the real "docs". My reasoning is simply that the wiki seems to be an easier and more productive medium for doing the work. I've spent a fair bit of time working on the in-program documentation (--help output, .doc files), and I find myself suddenly about 10 times more productive doing the same thing here -- the short-term feedback loop thing (watching what others changes, they watching what you change, and reacting to each other) is very useful. [Side note -- and of course, currently, the wiki is certainly more accurate than the old docs, as I've fixed a number of bogosities, and rewritten some confusing text while working on them here.]
  --MilesBader

help

tla help prints a list of the available commands.

To see just a list of the options to a particular command, use:
  tla $cmd -h
(where $cmd is the name of the command). For additional explanation about a given command, use:
  tla $cmd -H

User Commands

my-id : print or change your id

my-default-archive : print or change your default archive
register-archive : change an archive location registration
whereis-archive : print an archive location registration
archives : Report registered archives and their locations.

Project Tree Commands

init-tree : initialize a new project tree
tree-root : find and print the root of a project tree

tree-version : print the default version for a project tree
set-tree-version : set the default version for a project tree

undo : undo and save changes in a project tree
redo : redo changes in project tree

changes : report about local changes in a project tree
file-diffs : show local changes to a file

Project Tree Inventory Commands

inventory : inventory a source tree
tree-lint : audit a source tree
id : report the inventory id for a file

id-tagging-method : print or change a project tree id tagging method

add-id : add an explicit inventory id
add : (alias for add-id)
delete-id : remove an explicit inventory id
delete : (alias for delete-id)
move-id : move an explicit inventory id
move : (alias for move-id)
mv : move a file (or dir, or symlink) and it's explicit inventory tag (if any)
explicit-default : print or modify default ids
default-id : (alias for explicit-default)

id-tagging-defaults : print the default =tagging-method contents

Patch Set Commands

changeset : compute a whole-tree changeset
mkpatch : (alias for changeset)
apply-changeset : apply a whole-tree changeset
dopatch : (alias for apply-changeset)
show-changeset : generate a report from a changeset

Archive Transaction Commands

make-archive : create a new archive directory
archive-setup : create new categories, branches and versions

make-category : create a new archive category
make-branch : create a new archive branch
make-version : create a new archive version

import : archive a full-source base-0 revision
commit : archive a changeset-based revision

get : construct a project tree for a revision
get-changeset : retrieve a changeset from an archive

lock-revision : lock (or unlock) an archive revision
archive-mirror : update an archive mirror

Archive Commands

abrowse : print an outline describing archive contents
rbrowse : print an outline describing an archive's contents
categories : list the categories in an archive
branches : list the branches in an archive category
versions : list the versions in an archive branch
revisions : list the revisions in an archive version
ancestry : display the ancestory of a revision
ancestry-graph : display the ancestory of a revision

cat-archive-log : print the contents of an archived log entry

cacherev : cache a full source tree in an archive
cachedrevs : list cached revisions in an archive
uncacherev : remove a cached full source tree from an archive

archive-meta-info : report meta-info from an archive
archive-snapshot : update an archive snapshot
archive-version : list the archive-version in an archive

archive-fixup : fix ancillary files (e.g. .listing files) in an archive

Patch Log Commands

make-log : initialize a new log file entry
log-versions : list patch log versions in a project tree
add-log-version : add a patch log version to a project tree
remove-log-version : remove a version's patch log from a project tree
logs : list patch logs for a version in a project tree
cat-log : print the contents of a project tree log entry

changelog : generate a ChangeLog from a patch log

log-for-merge : generate a log entry body for a merge
merges : report where two branches have been merged
new-merges : list tree patches new to a version

Multi-project Configuration Commands

build-config : instantiate a multi-project config
cat-config : output information about a multi-project config

Commands for Branching and Merging

tag : create a continuation revision (aka tag or branch)

update : update a project tree to reflect recent archived changes
replay : apply revision changesets to a project tree
star-merge : merge mutually merged branches
apply-delta : Compute a changeset between any two trees or revisions and apply it to a project tree
missing : print patches missing from a project tree

join-branch : construct a project tree for a version
sync-tree : unify a project tree's patch-log with a given revision

delta : Compute a changeset between any two trees or revisions

Local Cache Commands

changes : report about local changes in a project tree
file-diffs : show local changes to a file
file-find : find given version of file

pristines : list pristine trees in a project tree
lock-pristine : lock (or unlock) a pristine tree
add-pristine : ensure that a project tree has a particular pristine revision
find-pristine : find and print the path to a pristine revision

Revision Library Commands

my-revision-library : print or change your revision library path
library-config : configure parameters of a revision library
library-find : find and print the location of a revision in the revision library
library-add : add a revision to the revision library
library-remove : remove a revision from the revision library
library-archives : list the archives in your revision library
library-categories : list the categories in your revision library
library-branches : list the branches in a library category
library-versions : list the versions in a library branch
library-revisions : list the revisions in a library version
library-log : output a log message from the revision library
library-file : find a file in a revision library

Published Revisions Commands

grab : grab a published revision

Miscellaneous Scripting Support

parse-package-name : parse a package name
valid-package-name : test a package name for validity

Commonly used options

Each command has its own set of options, but many command share some options, with similar semantics:

-H : Display a verbose help message and exit
-A, --archive : Override `my-default-archive'
-N, --forward : pass the --forward option to `patch'
-e, --errname : specify program name for errors
--link : hardlink unchanged files to revision library
--cache : cache root for trees with pristines
--skip-present : skip patches that contain 1 or more patch logs already in this tree
--strict : exit with non-0 status on any oddity
--three-way : Perform a 3-way (diff3-style) merge