tla(1)
✨ tla ✨ — the arch command line client tool 💅
ok so bestie, welcome to tla (that's the manual page name too, tla(1), in case you were wondering) — it's the arch command line client tool and honestly? she's iconic. 🎀
🌸 SYNOPSIS 🌸
like, here's the vibe of how you actually call her:
tla command [ command_options ]
tla command [-h|--help|-H]
tla [-h|--help|-H|-V|--version]so basically: a command, maybe some options for that command, or if you're just here to ask questions, there's help and version stuff. lowkey perfect. ✨
💖 DESCRIPTION 💖
tla is an implementation of arch. periodt.
and arch? bestie, arch is a version control system. she lets you keep old versions of files and directories (usually source code, because obviously 💅), and she keeps a log of who changed what, when, and why. like SVN, CVS, or RCS — but we're not comparing, we're just saying. 😌
and ngl, arch has a number of advantages compared to competing systems. among these are:
🌈 Works on Whole Trees 🌈
arch keeps track of whole trees — not just individual files. it's giving main character energy. 🦋
for example:
- if you change many files in a tree, arch can record all of those changes as a group rather than file-by-file. obsessed.
- if you rename files or reorganize a tree, arch can record those tree arrangements along with your changes to file contents. she sees everything. 👑
🎀 Changeset Oriented 🎀
arch doesn´t simply "snapshot" your project trees. no ma'am. 🙈
instead, arch associates each revision with a particular changeset: a description of exactly what has changed. and because of that, arch provides changeset oriented commands to help you:
- review changesets 🔍
- merge trees by applying changesets 🔀
- examine the history of a tree by asking what changesets have been applied to it 📜
- and so forth ✨
💜 Fully Distributed 💜
arch doesn´t rely on a central repository. literally not needed. 🧚
for example, there is no need to give write access to a project´s archive to all significant contributors. instead, each contributor can have their own archive for their work. and arch seamlessly operates across archive boundaries. slay. 💅
📜 COMMAND OVERVIEW ✨
okay bestie, here's the whole entire menu — every tla command that exists, sorted into little friend groups. no skimming, we're going through ALL of them. grab a snack. 🍓
🎀 Help
tla help [options]
asks arch for help. when you're lost, this is your emotional support command. 💖
👑 User Commands
tla my-id [options] [id]
prints your id, or changes it to whatever you hand it. your whole arch identity. main character badge. ✨
tla my-default-archive [options] [archive]
prints your default archive, or changes it. it's the "where do i actually live" setting. 🏠
tla register-archive [options] [archive] location
changes an archive location registration. you're telling arch where that archive is registered to be. 💅
tla whereis-archive [options] archive
prints where an archive's location is registered. bestie location services fr fr. 📍
tla archives [options] [search regular expression]
reports all your registered archives and their locations — and you can filter the list with a search regular expression. 🦋
🌳 Project Tree Commands
tla init-tree [options] [[archive]/version]
initializes a brand new project tree. the origin story, the birth of the vibe. 👑
tla tree-root [options] [dir]
finds the root of a project tree and prints it out. 💖
tla tree-version [options] [dir]
prints the default version for a project tree.
tla tree-id [options] [dir]
prints the tree identifier for a project tree.
tla tree-revision [options] [dir]
also prints the tree identifier for a project tree. same energy as the one above, and we respect that.
tla set-tree-version [options] [archive]/version
sets the default version for a project tree.
tla undo [options] [revision]
undoes changes in a project tree and saves them. the ctrl-z of your dreams. 😌
tla redo [options] [changeset]
redoes changes in a project tree.
tla changes [options] [revision] [-- limit...]
reports about the local changes in a project tree.
tla file-diff [options] file [revision]
shows the local changes to one specific file.
tla diff [options] [revision] [-- files...]
reports about the local changes in a project tree.
tla export [options] [revision] dir
exports all of a tree revision, or just some of it. 🎁
📦 Project Tree Inventory Commands
tla inventory [options] [--] [dir]*
does inventory on a source tree. like a stocktake but for your files. 🧾
tla tree-lint [options] [dir]
audits a source tree.
tla lint [options] [dir]
audits a source tree.
tla id [options] file ...
reports the inventory id for a file.
tla id-tagging-method [options] [method]
prints or changes a project tree's id tagging method. 💅
tla add [options] file ...
adds an explicit inventory id.
tla add-id [options] file ...
adds an explicit inventory id.
tla delete-id [options] file ...
removes an explicit inventory id.
tla move-id [options] from to
moves an explicit inventory id.
tla touch [options] file ...
adds an explicit inventory id, and touches the file while it's at it.
tla rm [options] file...
removes a file (or a dir, or a symlink) along with its explicit inventory tag. 💀
tla mv [options] from to OR from1 from2 ... dir
moves a file (or a dir, or a symlink) and its explicit inventory tag. two whole moods: rename it, or yeet a bunch of things into a dir.
tla explicit-default [options] [TAG-PREFIX]
prints or modifies the default ids.
tla default-id [options] [TAG-PREFIX]
prints or modifies the default ids.
tla id-tagging-defaults [options]
prints the default =tagging-method contents. 🌈
🩹 Patch Set Commands
tla changeset [options] ORIG MOD DEST [files]
computes a whole-tree changeset.
tla mkpatch [options] ORIG MOD DEST [files]
computes a whole-tree changeset.
tla apply-changeset [options] CHANGESET [TARGET]
applies a whole-tree changeset.
tla dopatch [options] CHANGESET [TARGET]
applies a whole-tree changeset.
tla show-changeset [options] [dir]
generates a report from a changeset. 📝
🏦 Archive Transaction Commands
tla make-archive [options] [name] location
creates a new archive directory.
tla archive-setup [options] [version ...]
creates new categories, branches and versions. the whole family tree, boom. 👑
tla make-category [options] category
creates a new archive category.
tla make-branch [options] branch
creates a new archive branch.
tla make-version [options] version
creates a new archive version.
tla import [options] [[archive]/version]
archives a full-source base-0 revision. 🚀
tla commit [options] [[archive]/version] [-- file ...]
archives a changeset-based revision.
tla get [options] revision [dir]
constructs a project tree for a revision.
tla get-changeset [options] revision [dir]
retrieves a changeset from an archive.
tla lock-revision [options] revision
locks (or unlocks) an archive revision. 🔒
tla archive-mirror [options] [from [to] [limit]]
updates an archive mirror.
🗄️ Archive Commands
tla abrowse [options] [limit]
prints an outline describing the archive contents.
tla rbrowse [options] [[ARCHIVE_NAME/]LIMIT_REGEX]
prints an outline describing an archive's contents.
tla categories [options] [archive]
lists the categories in an archive.
tla branches [options] [category]
lists the branches in an archive category.
tla versions [options] [branch]
lists the versions in an archive branch.
tla revisions [options] [version]
lists the revisions in an archive version.
tla ancestry [options] [revision]
displays the ancestry of a revision. 🌳
tla ancestry-graph [options] [revision]
displays the ancestry of a revision.
tla cat-archive-log [options] revision
prints the contents of an archived log entry.
tla cacherev [options] [revision]
caches a full source tree in an archive.
tla cachedrevs [options] [version]
lists the cached revisions in an archive.
tla uncacherev [options] revision [dir]
removes a cached full source tree from an archive.
tla archive-meta-info [options] item-name
reports meta-info from an archive. 🏷️
tla archive-snapshot [options] dir [limit]
updates an archive snapshot.
tla archive-version [options]
lists the archive-version in an archive.
tla archive-fixup [options]
fixes ancillary files in an archive. 🔧
📓 Patch Log Commands
tla make-log [options] [version]
initializes a new log file entry.
tla log-versions [options]
lists the patch log versions in a project tree.
tla add-log-version [options] [archive]/version
adds a patch log version to a project tree.
tla remove-log-version [options] [archive]/version
removes a version's patch log from a project tree.
tla logs [options] [[archive]/version ...]
lists the patch logs for a version in a project tree.
tla cat-log [options] revision-spec
prints the contents of a project tree log entry.
tla changelog [options] [[archive]/version]
generates a ChangeLog from a patch log. 💖
tla log-for-merge [options] [[archive]/version]
generates a log entry body for a merge.
tla merges [options] INTO [FROM]
reports where two branches have been merged.
tla new-merges [options] [[archive]/version]
lists the tree patches that are new to a version.
🧩 Multi-project Configuration Commands
tla build-config [options] config
instantiates a multi-project config.
tla cat-config [options] config
outputs information about a multi-project config. ✨
🌈 Commands for Branching and Merging
tla tag [options] SOURCE-REVISION TAG-VERSION
creates a continuation revision. 🏷️
tla branch [options] [SOURCE] BRANCH
creates a continuation revision.
tla switch [options] [package]
changes the working trees version.
tla update [options] [version/revision]
updates a project tree.
tla replay [options] [version/revision...]
applies revision changesets to a project tree.
tla star-merge [options] [FROM]
merges mutually merged branches. ⭐
tla apply-delta [options] FROM(REVISION|DIR) TO(REVISION|DIR)
computes a changeset between any two trees or revisions and applies it to a project tree.
tla missing [options] [version]
prints the patches that are missing from a project tree.
tla join-branch [options] version
adds a version as an ancestor of a project tree.
tla sync-tree [options] revision
unifies a project tree's patch-log with a given revision.
tla delta [options] (REVISION|TREE)-A (REVISION|TREE)-B [DESTDIR]
computes a changeset (or a diff) between any two trees or revisions. 💅
🗃️ Local Cache Commands
tla changes [options] [revision] [-- limit...]
reports about the local changes in a project tree.
tla file-diff [options] file [revision]
shows the local changes to a file.
tla file-find [options] file [revision]
finds a given version of a file.
tla pristines [options] [limit]
lists the pristine trees in a project tree.
tla lock-pristine [options] revision
locks (or unlocks) a pristine tree. 🔒
tla add-pristine [options] revision
ensures that a project tree has a particular pristine revision.
tla find-pristine [options] revision
finds a pristine revision and prints the path to it. 📍
📚 Revision Library Commands
tla my-revision-library [options] [dir]
prints your revision library path, or changes it.
tla library-config [options] library-dir
configures the parameters of a revision library.
tla library-find [options] revision
finds a revision in the revision library and prints its location.
tla library-add [options] revision
adds a revision to the revision library.
tla library-remove [options] revision
removes a revision from the revision library.
tla library-archives [options]
lists the archives in your revision library.
tla library-categories [options] [archive]
lists the categories in your revision library.
tla library-branches [options] [category]
lists the branches in a library category.
tla library-versions [options] [branch]
lists the versions in a library branch.
tla library-revisions [options] [version]
lists the revisions in a library version.
tla library-log [options] revision
outputs a log message from the revision library.
tla library-file [options] file revision
finds a file in a revision library. 🦋
📢 Published Revisions Commands
tla grab [options] location
grabs a published revision. no cap, that's genuinely what it does. 🤲
🛠️ Miscellaneous Scripting Support
tla parse-package-name [options] name
parses a package name.
tla valid-package-name [options] name
tests a package name for validity. ✅
tla escape [--unescaped] string
prints strings in escaped or unescaped form. ✨
🫶 HELP 🫶
🌸 tla help
bestie's little doorway to literally every other command — it gives you help with arch 💖
Usage: tla help [options]-h,--help— pops up a help message and dips out. short and sweet 🎀-H— the verbose help message, then exits. she's chatty, we love her 💅-b,--basic— show only the basic commands, no extras ✨-V,--version— print a release identifier string and exit 🦋
This command prints a list of the available commands. that's it, that's the whole job 💖
Wanna peek at just the options for one specific command? use:
tla $cmd -h(where $cmd is the name of the command). and if you want the full lore, the extra explanation about a given command, go:
tla $cmd -H👑 USER COMMANDS 👑
💜 tla my-id
print or change your id 🪪
Usage: tla my-id [options] [id]-h,--help— Display a help message and exit. 🎀-H— Display a verbose help message and exit. 💅-V,--version— Display a release identifier string and exit. 🦋-e,--errname— specify program name for errors 🌸-u,--uid— print only the UID portion of the ID ✨
With no argument, it prints your arch id. simple as that 💖
With an argument, it records ID-STRING as your id in ~/.arch-params/=id — so that's where your whole identity lives, no cap 🫶
Your id gets recorded in various archives and log messages as you use arch. it has to be entirely printable characters and fit on one line. by convention it should look like an email address, like this iconic example:
Jane Hacker <jane.hacker@gnu.org>The portion of an id string between < and > is called your uid. arch sometimes uses your uid as a fragment when generating unique file names 👑
The option -u (--uid) makes only the uid part of your id string get printed. just the inside bits, nothing else 💅
🦋 tla my-default-archive
print or change your default archive 🗂️
Usage: tla my-default-archive [options] [archive]-h,--help— Display a help message and exit. 🎀-H— Display a verbose help message and exit. 💅-V,--version— Display a release identifier string and exit. 🦋-A,--archive— Override `my-default-archive´ ✨-e,--errname— specify program name for errors 🌸-d,--delete— unspecify your default archive 💀-s,--silent— suppress reassuring messages 🙈
With no argument, and without -d, it prints the name of your default archive.
With an argument, it records ARCHIVE as your default archive in ~/.arch-params/=default-archive 💖
With the option -d (--delete) and no argument, it ensures you do not have a default archive set in ~/.arch-params. bye bestie 👋
Your default archive is determined this way, in order:
- If the option
-A(--archive) is given and not empty, that archive is the default (which makes this script useful for processing a-Aargument that was passed to another script). she's flexible like that 💅 - If
-Ais not given, but~/.arch-params/=default-archiveexists and is not empty, that is your default archive. ✨ - Otherwise, your default archive is the name of the local archive rooted at the argument to
-R(--root) or specified in the environment variableARCHROOT. 🌈
If no default archive can be found by any of these means, the program exits with status 1, printing an error message — unless the -s (--silent) option is given. so if you're getting a sad little exit 1, that's why 😭
🌸 tla register-archive
change an archive location registration 📍
Usage: tla register-archive [options] [archive] location-h,--help— Display a help message and exit. 🎀-H— Display a verbose help message and exit. 💅-V,--version— Display a release identifier string and exit. 🦋-f,--force— overwrite existing location 🔥--present-ok— return 0 even if archive exists ✅-d,--delete— delete archive registration 💀
Records the location of ARCHIVE.
With -d, it removes the registration of a previously registered archive. and when that's accompanied by -f, it overrides permissions on the registration file and doesn't complain if the archive is not registered. permission override, periodt. 💅
A LOCATION should be either a directory name or a distant URL. like, near or far, your call 🦋
When registering a new archive, if no ARCHIVE's name is passed on the command line, then the archive's name will be read automatically from the archive's meta data. it introduces itself, iconic behavior ✨
Archive locations are stored in ~/.arch-params/=locations 🗂️
You must register the location of a remote archive before you access it. no shortcuts, bestie 🚨
It is not strictly necessary to register the locations of local archives (you can always specify their location using command line arguments and/or environment variables), but registering local archive locations is recommend (for simplicity). lowkey just do it, future you says thank you 🫶
⭐ tla whereis-archive
print an archive location registration 🔎
Usage: tla whereis-archive [options] archive-h,--help— Display a help message and exit. 🎀-H— Display a verbose help message and exit. 💅-V,--version— Display a release identifier string and exit. 🦋
Prints the registered location of an archive.
Usually the archive must have been previously registered with "tla register-archive". ✨
As a special exception, if the archive is not registered, but is the name of the archive rooted at the location given with the option -R (--root) or in the environment variable ARCHROOT, then it prints that root directory. surprise shortcut!! 🌈
🎀 tla archives
report registered archives and their locations 📋
Usage: tla archives [options] [search regular expression]-h,--help— Display a help message and exit. 🎀-H— Display a verbose help message and exit. 💅-V,--version— Display a release identifier string and exit. 🦋-n,--names— print archive names only 🌸-R,--exclude-remote— Exclude MIRROR and SOURCE archives. 🙈
Prints a list of registered archives and their locations 💖
If [search regex] is given, then only archives with names that match [search regex] will be shown. filtering, we love to see it ✨
💖 PROJECT TREE COMMANDS 💖
okay bestie, this is the section where you actually live in your tree. setting it up, finding its root, checking its identity, undoing your chaos. it's giving main character energy for your working directory. 🫶
tla init-tree
initialize a new project tree
tla init-tree [options] [[archive]/version]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first--nested— initialize a nested project tree.
This makes DIR into a shiny brand-new project tree. ✨
An empty patch-log for VERSION gets created, and VERSION becomes the default place you check stuff in to. no cap, that's the whole vibe.
tla tree-root
find and print the root of a project tree
tla tree-root [options] [dir]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.--accurate— error for mid-txn trees-s,--silent— exit status only
Finds and prints the root of the project tree that DIR lives inside (or the current directory, if you didn't say).
The --accurate option checks for three possibilities, and bestie, this is the ✨drama✨ part:
- The project tree was the subject of a commit that was killed before the log entry was added to the tree's patch log. It is unknown whether or not the commit took place in the archive. The
{arch}directory contains the log file as"++mid-commit". - The project tree was the subject of a killed commit, but it is certain the commit took place. The log file is stored as
"++commit-definite". - The project tree patch log is fully up-to-date (as far as arch knows).
In case 1, exit with an error and error message. 😭
In case 2, install the log file before printing the tree root and exiting normally.
In case 3, print the tree root and exit normally. slay.
tla tree-version
print the default version for a project tree
tla tree-version [options] [dir]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.
Prints the default version of project tree DIR (or the current directory if you're being lazy about it 💅).
tla tree-id
Print the tree identifier for a project tree
tla tree-id [options] [dir]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.
Prints the patchset identifier that represents the current tree-> I.e. foo@example.com/demo--1.0--patch-4. Defaults to the tree the current directory is in.
tla tree-revision
Print the tree identifier for a project tree
tla tree-revision [options] [dir]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.
Prints the patchset identifier that represents the current tree-> I.e. foo@example.com/demo--1.0--patch-4. Defaults to the tree the current directory is in.
tla set-tree-version
set the default version for a project tree
tla set-tree-version [options] [archive]/version-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first
This operation sets the default version on which to check-in the source tree DIR (default: the current directory) during a commit. 🎀
You can specify the archive for this version as an ordinary command line argument (ARCHIVE/VERSION) or via -R, -A and the environment as usual (try tla my-default-archive --help). iykyk.
tla undo
undo and save changes in a project tree
tla undo [options] [revision]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first-o,--output PATCH-DIR— save changeset in PATCH-DIR-n,--no-output— do not save the changeset-N,--forward— pass the--forwardoption to `patch´-q,--quiet— no progress reports while computing changeset--unescaped— show filenames in unescaped form
Computes a patch set describing the changes from REVISION to the project tree containing DIR. Saves the patch in PATCH-DIR (which must not already exist, bestie, do not test this) and applies the patch in reverse to the project tree containing DIR.
The effect is to remove local changes in the DIR project tree but save them in a convenient form. it's giving "clean up your room but keep everything in a box" 🧚
If REVISION is not specified, the latest ancestor of the default version of project tree is used.
If REVISION is specified as a VERSION, the latest ancestor of the project tree in that VERSION is used.
If DIR is not specified, . is assumed.
If PATCH-DIR is not specified, a temporary file-name of the matching ,,undo-* is used.
If --no-output is specified, the patch set is not saved.
See also tla redo -H and tla changes -H.
tla redo
redo changes in project tree
tla redo [options] [changeset]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-N,--forward— pass the--forwardoption to `patch´-k,--keep— do not delete the patch-q,--quiet— no progress reports while computing changeset-d,--dir DIR— Operate on project tree in DIR (default `.´)--unescaped— show filenames in unescaped form
Applies CHANGESET to the project tree and then deletes CHANGESET. (yes, deletes. that's the deal.)
If CHANGESET is not specified, the highest numbered ,,undo-N directory in the project tree root is used.
If --keep is given, the changeset directory is not deleted.
See also tla undo --help and tla apply-changeset --help.
tla changes
report about local changes in a project tree
tla changes [options] [revision] [-- limit...]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´.-d,--dir DIR— Change to DIR first.-o,--output DIR— Save changeset in DIR (implies--keep).-v,--verbose— Verbose changeset report.-q,--quiet— Suppress progress information--diffs— Include diffs in the output.-k,--keep— Don´t remove the output directory on termination.--link— hardlink unchanged files to revision library--unescaped— show filenames in unescaped form
Generates a patch report describing the differences between the project tree containing DIR (or the current directory) and REVISION. 🦋
The default patch level for a given version is the latest level for which the project tree has a patch. The default archive and version is as printed by tla tree-version.
tla file-diff
show local changes to a file
tla file-diff [options] file [revision]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´-N,--new-file— Treat missing file as empty
Prints diffs between FILE and the corresponding file in a cached copy of REVISION. just the one file, just for you 💅
The default patch level for a given version is the latest level for which the project tree has a patch. The default archive and version is as printed by tla tree-version.
tla diff
report about local changes in a project tree
tla diff [options] [revision] [-- files...]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´.-d,--dir DIR— Change to DIR first.-o,--output DIR— Save changeset in DIR.-v,--verbose— Verbose changeset report.-q,--quiet— Suppress progress information-s,--summary— Do not include diffs in the output.-k,--keep— Don´t remove the output directory on termination.-L,--latest— compare against the latest revision (HEAD) in branch--link— hardlink unchanged files to revision library--unescaped— show filenames in unescaped form--limit LIMITS— limit the diff to LIMITS-D,--diff-options— specify options for `diff´ (for display only)
Generates a patch report describing the differences between the project tree containing DIR (or the current directory) and REVISION.
The default patch level for a given version is the latest level for which the project tree has a patch. The default archive and version is as printed by tla tree-version.
tla export
export all or some of a tree revision
tla export [options] [revision] dir-d,--dir DIR— Change to DIR first.-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-s,--silent— no output
Extracts REVISION from an archive, creating a new source tree with no control information. Note if export the local tree revision, local modifications will not be included; the exported file will only be copies in the repository.
⚠️ bestie read that again: your local edits do NOT come along for the ride. it's the repository copy only. no cap.
🦋 PROJECT TREE INVENTORY COMMANDS 🦋
tla inventory
inventory a source tree
tla inventory [options] [--] [dir]*-h,--help— display help-H— show a verbose help message and dip.-V,--version— display version info-s,--source— list source files-p,--precious— list precious files-b,--backups— list backup files-j,--junk— list junk files-u,--unrecognized— list unrecognized files-t,--trees— list roots of nested trees-d,--directories— list only directories-f,--files— list only non-directories-B,--both— list both dirs and files--kind— indicate file kinds--all— include arch control files--nested— include nested trees
okay that's the tree stuff 💜 keep going, there's more 👑
--ids— list with ids (source files only) 💅--untagged— include files that are missing ids, we love an inclusive queen 🫶--explicit— use explicit file ids--implicit— permit implicit file ids--tagline— permit tagline file ids--names— use name-based file ids--unescaped— show filenames in unescaped form
With no arguments, it prints a human-readable inventory report. periodt
With category options (--source etc), limit the report to just those files. With no other options, the report includes all sections and files.
The options -d, -f, and -b cancel each other. mutually exclusive, bestie
If a directory is precious, junk, or unrecognized, only the directory name itself is printed -- its contents are not searched. no digging deeper, okay?
Each command option implies the corresponding category option (e.g. "--source-command" implies "--source"). The exit status of the command is ignored. we literally do not care about its exit status
tla tree-lint
(alias for lint) — okay bestie, it's giving audit energy.
Usage:
Usage: tla tree-lint [options] [dir]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-s,--broken-symlinks— Just list broken symlinks-u,--unrecognized-files— Just list files violating naming conventions-t,--untagged-files— Just list files lacking inventory ids-m,--missing-files— Just list inventory ids lacking corresponding files-d,--duplicate-ids— Just list duplicated ids--strict— exit with non-0 status on _any_ oddity--unescaped— show filenames in unescaped form
Audit a source tree for missing files, untagged files, duplicate ids, and files not matching recognized naming conventions. full detective mode 🔍
The default is to list files failing any of those tests. Enabling any of the specific tests disables the rest, unless they're explicitly enabled on the command line. Therefore, "tla tree-lint" is equivalent to "tla tree-lint -sutmd". slay
tla lint
audit a source tree
Usage:
Usage: tla lint [options] [dir]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-s,--broken-symlinks— Just list broken symlinks-u,--unrecognized-files— Just list files violating naming conventions-t,--untagged-files— Just list files lacking inventory ids-m,--missing-files— Just list inventory ids lacking corresponding files-d,--duplicate-ids— Just list duplicated ids--strict— exit with non-0 status on _any_ oddity--unescaped— show filenames in unescaped form
Audit a source tree for missing files, untagged files, duplicate ids, and files not matching recognized naming conventions. full detective mode 🔍
The default is to list files failing any of those tests. Enabling any of the specific tests disables the rest, unless they're explicitly enabled on the command line. Therefore, "tla tree-lint" is equivalent to "tla tree-lint -sutmd". slay
tla id
report the inventory id for a file
Usage:
Usage: tla id [options] file ...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.--implicit— Use the implicit id tagging method.--tagline— Use the tagline id tagging method (default).--explicit— Use the explicit id tagging method.--names— Use the names id tagging method.--silent— No output -- exit status only.--unescaped— show filenames in unescaped form
Print a file's inventory id. just the id, bestie
tla id-tagging-method
print or change a project tree id tagging method
Usage:
Usage: tla id-tagging-method [options] [method]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-d,--dir DIR— cd to DIR first--strict— exit with error if method not set
Print or change the method by which source files are identified in DIR (or the current directory).
When setting, METHOD must be one of:
names -- use naming conventions only
implicit -- use naming conventions but permit
for inventory tags
explicit -- require explicit designation of source
tagline -- mix names, explicit and arch-tag: methodsWhen printing, if --strict is provided but no id tagging method is explicitly set, print an error. strict mode activated
tla add
(alias for add-id) — same energy, different name.
Usage:
Usage: tla add [options] file ...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-i,--id ID— Specify ID, instead of using auto-generated id.
Create an explicit inventory id for FILE (which may be a regular file, symbolic link, or directory). glow up your tree ✨
tla add-id
add an explicit inventory id
Usage:
Usage: tla add-id [options] file ...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-i,--id ID— Specify ID, instead of using auto-generated id.
Create an explicit inventory id for FILE (which may be a regular file, symbolic link, or directory). glow up your tree ✨
tla delete-id
remove an explicit inventory id
Usage:
Usage: tla delete-id [options] file ...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.
Remove an explicit inventory id for FILE (which may be a regular file, symbolic link, or directory). bye bestie 💅
tla move-id
move an explicit inventory id
Usage:
Usage: tla move-id [options] from toOptions:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.
Move an explicit inventory id for FILE (which may be a regular file or symbolic link but which must not be a directory). no directories allowed, sorry
tla touch
add an explicit inventory id, touching the file.
Usage:
Usage: tla touch [options] file ...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-i,--id ID— Specify ID, instead of using auto-generated id.
Create an explicit inventory id for FILE (which may be a regular file, symbolic link, or directory). This command also sets the modification and access times of the file, creating it if necessary. touch grass? no, touch file
tla rm
remove a file (or dir, or symlink) and its explicit inventory tag
Usage:
Usage: tla rm [options] file...Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.
This command is suitable as a replacement for rm(1) within any tla tree for any remove operation, regardless of id tagging method. careful, bestie, it deletes
tla mv
move a file (or dir, or symlink) and its explicit inventory tag
Usage:
Usage: tla mv [options] from to OR from1 from2 ... dirOptions:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.
This command is suitable as a replacement for mv(1) within any tla tree for any move operation, regardless of id tagging method.
tla explicit-default
print or modify default ids
Usage:
Usage: tla explicit-default [options] [TAG-PREFIX]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-D,--dir DIR— cd to DIR first-d,--delete— remove the default-s,--strong— use the strong default (default)-w,--weak— use the weak default--dont-care— use the dont-care default
For files in this directory, use:
ID-PREFIX__BASENAMEas the default explicit id for all files in this directory that do not have an explicit explicit id.
With no arguments, print the previously set ID-PREFIX.
By default, this command sets, prints or deletes a "strong default" -- a default explicit id which overrides implicit ids.
With --weak, set (or print) a weak default id which is overridden by explicit ids.
The --dont-care option sets (or with -d, clears) a flag for that directory that causes unidged files not to be reported as such in "tla tree-lint" reports. dont-care vibes
tla default-id
(alias for explicit-default) — same thing, different name.
Usage:
Usage: tla default-id [options] [TAG-PREFIX]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-D,--dir DIR— cd to DIR first-d,--delete— remove the default-s,--strong— use the strong default (default)-w,--weak— use the weak default--dont-care— use the dont-care default
For files in this directory, use:
ID-PREFIX__BASENAMEas the default explicit id for all files in this directory that do not have an explicit explicit id.
With no arguments, print the previously set ID-PREFIX.
By default, this command sets, prints or deletes a "strong default" -- a default explicit id which overrides implicit ids.
With --weak, set (or print) a weak default id which is overridden by explicit ids.
The --dont-care option sets (or with -d, clears) a flag for that directory that causes unidged files not to be reported as such in "tla tree-lint" reports. dont-care vibes
tla id-tagging-defaults
print the default =tagging-method contents
Usage:
Usage: tla id-tagging-defaults [options]Options:
-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.
Print the boilerplate contents that are used to initialize new =tagging-method files. boilerplate but make it cute
🌈 PATCH SET COMMANDS 🌈
💖 tla changeset
bestie, this one computes a whole-tree changeset. iconic behavior.
Usage:
tla changeset [options] ORIG MOD DEST [files]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.--file-list FILES— record only diffs of selected files--unescaped— show filenames in unescaped form
Create the output directory DESTINATION (it must not already exist). no cap, it has to be brand new. ✨
Compare source trees ORIGINAL and MODIFIED. Create a changeset tree in DESTINATION. it's giving "here's everything that changed" 🦋
See also tla apply-changeset -H.
🎀 tla mkpatch
(alias for changeset)
Usage:
tla mkpatch [options] ORIG MOD DEST [files]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.--file-list FILES— record only diffs of selected files--unescaped— show filenames in unescaped form
Create the output directory DESTINATION (it must not already exist). lowkey important, it cannot exist already 💅
Compare source trees ORIGINAL and MODIFIED. Create a changeset tree in DESTINATION.
See also tla apply-changeset -H.
🦋 tla apply-changeset
apply a whole-tree changeset. the moment we've all been waiting for 🫶
Usage:
tla apply-changeset [options] CHANGESET [TARGET]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-N,--forward— pass the--forwardoption topatch-r,--reverse— Apply the changeset in reverse--unescaped— show filenames in unescaped form
Apply the changeset CHANGESET to the source tree TARGET (default .).
See also tla changeset -H.
🌸 tla dopatch
(alias for apply-changeset)
Usage:
tla dopatch [options] CHANGESET [TARGET]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-N,--forward— pass the--forwardoption topatch-r,--reverse— Apply the changeset in reverse--unescaped— show filenames in unescaped form
Apply the changeset CHANGESET to the source tree TARGET (default .).
See also tla changeset -H.
⭐ tla show-changeset
generate a report from a changeset. it's giving receipts, but make it readable 📝
Usage:
tla show-changeset [options] [dir]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.--diffs— include diff output--unescaped— show filenames in unescaped form
Produce a human-readable summary of a changeset.
👑 ARCHIVE TRANSACTION COMMANDS 👑
💜 tla make-archive
create a new archive directory. literally building the whole empire from scratch 💅
Usage:
tla make-archive [options] [name] location-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-m,--mirror MASTER— create mirror of specified archive-M,--mirror-from MASTER-SOURCE— create pull-based mirror of specified archive-l,--listing— Keep.listingfiles up-to-date in this archive.-t,--tla— Create a tla format archive.-b,--baz— Create a baz format archive (the default).-s,--signed— GPG sign the contents of this archive.
NAME is the global name for the archive. bestie it has RULES: it must be an email address with a fully qualified domain name, optionally followed by -- and a string of letters, digits, periods and dashes. no skipping steps fr fr 🎀
With --mirror, label the new archive as a mirror of MASTER. Ordinary commits can not be made to a mirror archive, however the command tla archive-mirror can write to a mirror. so like... only that one special command gets the keys to the kingdom 🔑
Two special forms of this command are available:
tla make-archive --mirror MASTER LOCATIONis equivalent to:
tla make-archive --mirror MASTER MASTER-MIRROR LOCATIONand thus tla archive-mirror MASTER will push changes from MASTER to the newly created mirror.
tla make-archive --mirror-from MASTER-SOURCE LOCATIONis equivalent to:
tla make-archive --mirror MASTER-SOURCE MASTER LOCATIONand thus tla archive-mirror MASTER will pull changes from MASTER-SOURCE to the newly created mirror.
The first of these two special forms is especially handy when creating a remote mirror in which to publish a local repository.
The second special form is handy when creating a local mirror of a remote archive, locally bound to the remote archive's name.
The --tla option creates a tla format archive, the default is to create a Bazaar archive. 🌸
🧚 tla archive-setup
create new categories, branches and versions. the full glow-up pipeline ✨
Usage:
tla archive-setup [options] [version ...]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-f,--file FILE— read the list of desired versions fromFILE-b,--branches— make base-0 tags-c,--cache— archive cache when creating base-0 tags
Given a list of categories, branches, and versions, ensure that these exist in the appropriate archive. it's giving "manifesting but it actually works" 💫
For example, starting with an empty archive,:
% tla archive-setup proja--devo--1.0 projbcreates a category, branch, and version for project A, and a category for project B.
When the --file option is used, the list of items to create is read from a file (use - to indicate standard input).
With the --file option, the option --branches may be provided. In this case, the input should have two items per line: a target version (to create), and a source version to build a tag from. For example, given an input file containg:
proja--devo--1.0 his@foo.com/proja--devo--1.0with --branches, archive-setup creates a proja version in your default archive, and adds a base-0 revision to that project which is a tag of the latest revision in his@foo.com's archive. (This can make it quite easy to set-up a new archive which contains branches from existing archives, for example.) so basically you can steal... I mean borrow... a whole branch setup 😭 iconic
If --branches is used, the --cache option may also be used. It causes each new base-0 revision to be archive-cached (see tla cacherev -H).
🎀 tla make-category
create a new archive category. tiny step, big vibes 🦋
Usage:
tla make-category [options] category-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive
Create CATEGORY as a category in the indicated archive. The category must not already exist. sorry bestie, no duplicates 💅
🌈 tla make-branch
create a new archive branch. branching out, main character energy fr 🌿
Usage:
tla make-branch [options] branch-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive
Create BRANCH as a branch in the indicated archive.
The category containing the branch must already exist. so like, category first, branch second, no cutting the line 🎀
⭐ tla make-version
create a new archive version. the final piece of the setup trio ✨
Usage:
tla make-version [options] version-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive
Create VERSION as a version in the indicated archive. The branch for this version must not already exist. yep, still no duplicates 🙈
🔥 tla import
archive a full-source base-0 revision. this is THE origin story, the first commit ever 🫶
Usage:
tla import [options] [[archive]/version]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive.-d,--dir DIR— Change toDIRfirst.-l,--log FILE— Commit with log fileFILE.-s,--summary TEXT— log with summaryTEXTplus log-for-merge output-L,--log-message TEXT— log withTEXT-S,--setup— Usearchive-setupif necessary; implied by default.--no-setup— Do not usearchive-setupeven if necessary.--unescaped— show filenames in unescaped form
Archive a from-scratch base revision of the project tree containing DIR (or the current directory). Use this command to create the first revision of a new project. it's giving "hello world but make it official" 🌍
If --log-message is specified without --summary, then TEXT is used both as the summary and the first line of the log body. two jobs, one flag 💅
💖 tla commit
archive a changeset-based revision. the everyday slay 💖
Usage:
tla commit [options] [[archive]/version] [-- file ...]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd toDIRfirst-l,--log FILE— commit with log fileFILE-s,--summary TEXT— log with summaryTEXTplus log-for-merge output-L,--log-message TEXT— log withTEXTplus log-for-merge output--strict— strict tree-lint--seal— create a version-0 revision--fix— create a versionfix revision--out-of-date-ok— commit even if out of date--file-list FILE— commit only changes to files listed inFILE--write-revision REVISION_FILE_SPEC— write the new tree id toREVISION_FILE_SPECbefore committing--unescaped— show filenames in unescaped form
Archive a revision of the project tree containing DIR (or the current directory).
If there are any automated ChangeLog files, update them before computing the patch set. yes bestie, it tidies up before it commits, we love a self-maintaining queen 👑
If --log-message is specified without --summary, then TEXT is used both as the summary and the first line of the log body. bestie that's just how it works 💅
tla get
okay so this one constructs a project tree for a revision ✨
Usage: tla get [options] revision [dir]-h,--help— show a help message and dip.-H— show a verbose help message and dip (the deluxe version 🎀).-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´ 👑--cache DIR— cache root for trees with pristines--no-pristine— don´t save a pristine copy--link— hardlink files to revision library instead of copying--library— ensure the revision is in a revision library--sparse— add library entries sparsely (--link,--library)--non-sparse— add library entries densely (--link,--library)-s,--silent— no output 🤫--no-greedy-add— do not allow greedy libraries to add revisions--unescaped— show filenames in unescaped form
Extract REVISION from an archive, creating the new project tree DIR. If DIR is not specified, store the working copy in a subdirectory of the current directory, giving it the name of the revision.
🚨 CAUTION: when using the links option be sure to use copy-on-write on your editor or the revision library will be corrupted. Either way, the project tree must not already exist. like, it literally cannot already exist, no exceptions 🙈
tla get-changeset
retrieve a changeset from an archive 🦋
Usage: tla get-changeset [options] revision [dir]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´
Retrieve the changeset for REVISION and store it in the directory DIR (or a directory named REVISION.patches). DIR must not already exist. that's the vibe check and it must pass 💖
tla lock-revision
lock (or unlock) an archive revision 🔒
Usage: tla lock-revision [options] revision-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-u,--unlock— release a lock owned by you-b,--break— break any existing lock
Acquire the lock needed to create REVISION.
Revision must be the next patch-level in sequence, however, if no patch level is specified, the lock is taken unconditionally. If no version is specified, the latest version is locked. periodt 💅
tla archive-mirror
update an archive mirror 🪞
Usage: tla archive-mirror [options] [from [to] [limit]]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.--no-cached— don´t copy cached revisions-s,--summary— print the summary of each patch--cached-tags— copy only cachedrevs for tags to other archives
If no arguments are given, update your my-default-archive´-MIRROR archive with the contents of my-default-archive´.
If a [FROM] archive is given, update the [FROM]-MIRROR archive with the contents of the [FROM] archive 🌸
If both [FROM] and [TO] archives are specified, update [TO] with the contents of [FROM]
If LIMIT is provided, it should be a category, branch, version, or revision name. Only the indicated part of FROM will be copied to TO. If LIMIT is a revision, then cached revisions will be copied and deleted to TO. no cap.
(see "tla make-archive -H".). iykyk 👑
✨ ARCHIVE COMMANDS ✨
tla abrowse
print an outline describing archive contents 🗺️
Usage: tla abrowse [options] [limit]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-r,--reverse— sort revisions from newest to oldest-s,--summary— print a summary of each patch-c,--creator— print the creator of each patch-D,--date— print the date of each patch-k,--kind— show each revision kind (import, changeset or id)-C,--cacherevs— show cached revisions-f,--full— print full patch level names--desc— implies-s-c-D-k-C--local-merges— list merges from the same archive--foreign-merges— list merges from other archives--merges— list all merges--categories— show category names only--branches— show branch names only--versions— show version names only--omit-empty— omit empty or unchanged-since items--since SNAP-FILE— show revisions after those listed in SNAP-FILE--since-limits— limit output to items in the since file--snap SNAP-FILE— record the highest revisions shown--force— overwrite an existing snap-file
Describe the contents of an archive in outline format. 🦋
With LIMIT, look only that part of the archive.
LIMIT may be a fully qualified name and may be an archive name.
tla rbrowse
print an outline describing an archive´s contents 🌈
Usage: tla rbrowse [options] [[ARCHIVE_NAME/]LIMIT_REGEX]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string--all— search all archives--since SNAP-FILE— only show differences since SNAP-FILE--snap SNAP-FILE— snap an archive-f,--snap-force— force snap writing-r— reverse patch logs-s— print the summary of matching patches-c— print the creator of matching patches-D— print the date of matching patches--patch-regex REGEX— only show revisions that contain [REGEX] (implies-s)-A,--archive— use [archive] instead of default--show-sealed— do not hide sealed branches
an outline of an archive will be printed, showing the categories, branches and revisions of the specified archive if no archive is given then my-default-archive is used.
If [LIMIT REGEX] is specified, revisions will only be shown if the category, branch or version matches [LIMIT REGEX]. If --patch-regex [REGEX] is given, then only patchlogs matching [REGEX] will be given 💖
tla categories
list the categories in an archive 🏷️
Usage: tla categories [options] [archive]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´
Print a list of the categories present in an archive.
tla branches
list the branches in an archive category 🌿
Usage: tla branches [options] [category]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´
Print a list of the branches within CATEGORY
tla versions
list the versions in an archive branch 📦
Usage: tla versions [options] [branch]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-r,--reverse— sort from newest to oldest
Print a list of versions within an archive branch.
The list is ordinarily sorted from oldest to newest, but the order can be changed with -r (--reverse). 💫
tla revisions
list the revisions in an archive version 🎀
Usage: tla revisions [options] [version]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-r,--reverse— sort from newest to oldest-f,--full— list fully qualified names-s,--summary— print a summary of each patch-c,--creator— print the creator of each patch-D,--date— print the date of each patch
Print a list of revisions within an archive version.
The list is ordinarily sorted from oldest to newest, but the order can be changed with -r (--reverse).
With optional arguments specifying patches, list only those patches, if they exist. If a listed patch does not exist, exit with status 1. The -r (--reverse) flag has no effect with optional arguments. 💅
tla ancestry
display the ancestory of a revision 🌳
Usage: tla ancestry [options] [revision]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first-m,--merges— show merges into this development line-r,--reverse— list oldest to newest-s,--summary— print a summary of each patch-c,--creator— print the creator of each patch-D,--date— print the date of each patch
Print the ancestry of a revision.
tla ancestry-graph
display the ancestory of a revision 🌲
Usage: tla ancestry-graph [options] [revision]-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first-m,--merges— show merges into this development line-r,--reverse— list oldest to newest-i,--immediate— show only the immediate ancestor-p,--previous— show the (namespace) previous revision
Print a list describing the ancestry of a revision.
tla cat-archive-log
print the contents of an archived log entry 📜
Usage: tla cat-archive-log [options] revision-h,--help— display a help message and exit.-H— display a verbose help message and exit.-V,--version— display a release identifier string and exit.-A,--archive— override `my-default-archive´--headers— show only log headers
like, just the headers, bestie 🎀
from its archive. boom — that's the whole vibe, bestie: the log message for the revision you asked for, pulled straight out of the archive and printed for you. 💖
🗂️ tla cacherev — cache a full source tree in an archive
Usage:
tla cacherev [options] [revision]Options, bestie, all of them:
-h,--help— show a help message and dip. ✨-H— show a verbose help message and dip. the long one. the yapper. 🫶-V,--version— print a release identifier string and dip.-A,--archive— override `my-default-archive´. like, do it for a different archive than your usual one. 👑--cache DIR— cache root for trees with pristines.
So what does it do, you ask? It caches a full-text copy of the indicated revision in the archive. iconic And the payoff? It can speed up subsequent calls to "tla get" for that revision and the ones after it. literally free real estate. 🔥
And if you don't specify a revision but you're chillin' inside a project tree, it caches the latest revision in the default version of that tree. it just knows. 💅
📜 tla cachedrevs — list cached revisions in an archive
Usage:
tla cachedrevs [options] [version]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
It reports which revisions of VERSION have been cached as whole trees in the archive. like a little roll call of everything that's already been cached. 🎀
See also "tla cacherev -H". 🦋
🗑️ tla uncacherev — remove a cached full source tree from an archive
Usage:
tla uncacherev [options] revision [dir]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
It removes the cached form of REVISION from its archive. bye bye cache. 👋
If REVISION is not specified, but the command is run from within a project tree, it uncaches the latest revision in the default version of that tree.
Also see "tla cacherev -H".
🔍 tla archive-meta-info — report meta-info from an archive
Usage:
tla archive-meta-info [options] item-name-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
It prints the contents of a meta-info file from an archive. For example:
% tla archive-meta-info nameprints the official name of your default archive. cute lil identity check for your archive. 💜
📸 tla archive-snapshot — update an archive snapshot
Usage:
tla archive-snapshot [options] dir [limit]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
It updates the directory DIR with a "snapshot" of an archive — or, like, the part of the archive that LIMIT points at.
For each archive snapshotted, DIR will contain a file and a subdirectory, where $ARCH is the name of the archive:
./$ARCH.added
./$ARCH/Similarly, for each category snapshotted, DIR will contain:
./$ARCH/$CAT.added
./$ARCH/$CAT/and so on, recursively, for branches and versions. it goes all the way down. 🌀
For each revision, the snapshot contains:
./$ARCH/$CAT/$BRANCH/$VERSION/$REVISION.addedand that file contains a copy of the patch log entry for that revision.
Snapshots can be used in combination with other tools (make is suggested) to trigger one-time events in response to new additions to an archive. automation girlies, this one's for you. ⭐
🏷️ tla archive-version — list the archive-version in an archive
Usage:
tla archive-version [options]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
It prints the archive format identifier string of an arch archive. like the archive's little birth certificate. 📄✨
🔧 tla archive-fixup — fix ancillary files in an archive
Usage:
tla archive-fixup [options]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´.
This one is a kind of "catch-all" command — it's here to fix the non-standard, non-transactional state of an archive. 🩹
rn its sole function is repairing .listing files in archives that use them. so if your archive is feeling messy in exactly that way, this is the glow-up appointment. 💅
🌸 PATCH LOG COMMANDS 🌸
okay bestie this is the part where tla keeps a little diary for ur tree and honestly it's giving ✨annotated history✨
tla make-log
<h3>initialize a new log file entry 🎀</h3>
Usage:
tla make-log [options] [version]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first
Create (if needed) a log entry file in the root of the project tree containing DIR, for the indicated VERSION. 💖
The name of the new log file is printed to standard output. 🦋
tla log-versions
<h3>list patch log versions in a project tree 🌈</h3>
Usage:
tla log-versions [options]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-d,--dir DIR— cd to DIR first-a,--archive ARCHIVE— list only logs for ARCHIVE-c,--category CATEGORY— list only logs for CATEGORY-b,--branch BRANCH— list only logs for BRANCH-v,--vsn VERSION— list only logs for VERSION-r,--reverse— reverse the sort order
Print the list of versions for which there are patch logs in the project tree containing DIR (or the current directory). 📋
tla add-log-version
<h3>add a patch log version to a project tree ✨</h3>
Usage:
tla add-log-version [options] [archive]/version-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first
Add an initially empty list of patch log for VERSION to the project tree containing DIR (or the current directory). 🫶
A project tree patch log is a pre-requisite for checking the directory in on that version, or updating with patches from that version. (yes bestie, prerequisite. u literally cannot do the thing without it.)
Note that versions recorded for a project tree are recorded by fully qualified version names: an archive name plus the name of a version within that archive. 💅
tla remove-log-version
<h3>remove a version's patch log from a project tree 💀</h3>
Usage:
tla remove-log-version [options] [archive]/version-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first
Remove the patch log for VERSION from the project tree containing DIR (or the current directory).
Use this command with caution — it erases revision history from the project tree! 🚨 bestie. it is LITERALLY eating ur history. be so fr before u type this one.
tla logs
<h3>list patch logs for a version in a project tree 🌸</h3>
Usage:
tla logs [options] [[archive]/version ...]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first-r,--reverse— sort from newest to oldest-s,--summary— print the summary of each patch-c,--creator— print the creator of each patch-D,--date— print the date of each patch--local-merges— list merges from the same archive--foreign-merges— list merges from other archives--merges— list all merges-f,--full— print full patch level names
Print the list of patches applied to a project tree DIR (or the current directory) from VERSION. 👑
tla cat-log
<h3>print the contents of a project tree log entry 🎀</h3>
Usage:
tla cat-log [options] revision-spec-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first
Retrieve and print the patch log for the indicated revision from a project tree. it's literally cat but for the diary entry bestie 💖
tla changelog
<h3>generate a ChangeLog from a patch log ✨</h3>
Usage:
tla changelog [options] [[archive]/version]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first--no-files— exclude file lists from ChangeLog--untagged— don't implicitly tag the output file--new-entry PATCH,FILE— make FILE the first (top) entry for patch level PATCH
Generate a ChangeLog for VERSION from the patch log for DIR. 🌈
tla log-for-merge
<h3>generate a log entry body for a merge 🦋</h3>
Usage:
tla log-for-merge [options] [[archive]/version]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first-r,--reverse— sort from newest to oldest
Generate a log entry body describing a merge into VERSION. 💌
tla merges
<h3>report where two branches have been merged 🔥</h3>
Usage:
tla merges [options] INTO [FROM]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first-r,--reverse— sort from newest to oldest-f,--full— print full patch level names
Print a list of pairs of patch level names:
%s %s INTO-RVN FROM-RVNwhere each pair indicates that at patch level INTO-RVN of INTO, the patch log entry FROM-RVN was added.
FROM may be a branch name, version name, or revision name. If a branch or version name, all merges from that branch or version are reported. If a revision name, only the merge points for that specific revision are reported.
INTO may be a version name or revision name. If a version name, all merge points within that version are printed. If a revision name, all merge points at that revision or earlier are printed.
Output is sorted using patch-level ordering of the first column. 📊
Included patches are listed by full name unless FROM is a revision name. If FROM is a revision, --full causes its full name to be printed.
tla new-merges
<h3>list tree patches new to a version ⭐</h3>
Usage:
tla new-merges [options] [[archive]/version]-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-d,--dir DIR— cd to DIR first-r,--reverse— sort from newest to oldest
List all patch log entries in the tree containing DIR that have not already been merged with VERSION. (the "who even are u" list ✨)
🧚 MULTI-PROJECT CONFIGURATION COMMANDS 🧚
tla build-config
<h3>instantiate a multi-project config 🏗️</h3>
Usage:
tla build-config [options] config-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-d,--dir DIR— cd to DIR first--no-pristines— don't create pristine copies--link— hardlink files to revision library instead of copying--library— ensure revisions are in the revision library--sparse— add library entries sparsely (--link,--library)-r,--release-id— overwrite./=RELEASE-IDfor this config
Build the named configuration. See also tla cat-config -H. 👑
tla cat-config
<h3>output information about a multi-project config 🎀</h3>
Usage:
tla cat-config [options] config-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-d,--dir DIR— cd to DIR first-o,--output CFG— write the output as config CFG-f,--force— overwrite an exiting config (with--output)-s,--snap— Show current patch levels of subtree packages.--unescaped— show filenames in unescaped form
Parse and print the indicate config file from a project tree 📖
A config file contains blank lines, comment lines starting with #, and config specification lines. The config file called $NAME is stored in a project tree as ./configs/$NAME or as ./$NAME.
A config specification line contains a relative path within a project tree, and a specification of the project or revision to store in that location.
For example, the line:
./src/arch lord@emf.net--2003b/arch--devo--1.0means that, when building the configuration, the latest revision of arch--devo--1.0 should be created within the tree as ./src/arch.
The project specification can be a branch name, version name or the name of a specific revision.
The option --snap says to examine the project tree to find out which revisions of configured project are printed, and generate a new config specification that references those specific revisions. For example, the output for the line shown above might be:
./src/arch lord@emf.net--2003b/arch--devo--1.0--patch-21The option --output causes the output from this command to be recorded as a new configuration file (or to replace an existing file if --force is provided). 💾
💅 COMMANDS FOR BRANCHING AND MERGING 💅
tla tag
<h3>create a continuation revision 🦋</h3>
Usage:
tla tag [options] SOURCE-REVISION TAG-VERSION-h,--help— Display a help message and exit.-H— Display a verbose help message and exit.-V,--version— Display a release identifier string and exit.-A,--archive— Overridemy-default-archive-l,--log FILE— commit with log file FILE--no-cacherev— Do not cacherev tag even if different archive--seal— create a version-0 revision--fix— create a versionfix revision-S,--setup— Usearchive-setupif necessary; implied by default.--no-setup— Do not usearchive-setupeven if necessary.
Create the continuation revision TAG-VERSION (branch point or tag) which is equivalent to SOURCE-REVISION (plus a log entry). ✨ main character energy fr fr
If no log entry is provided, a trivial log entry will be created. 💖
🌿 tla branch — create a continuation revision
tla branch [options] [SOURCE] BRANCH-h,--help— show a help message and dip. ✨-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive👑-l,--log FILE— commit with log fileFILE--no-cacherev— do not cacherev tag, even if the archive is different--seal— create a version-0 revision 🔥--fix— create a versionfix revision
So basically: create the continuation revision BRANCH (a branch point or a tag, bestie) which is equivalent to SOURCE — plus a log entry, obviously. If no log entry is provided, a trivial one gets created for you, no stress. 🫶
If SOURCE isn't specified, the current project tree revision is used, and the project tree gets switched to BRANCH. The way that just happens for you? iconic.
🔄 tla switch — change the working trees version
tla switch [options] [package]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive.-d,--dir DIR— change toDIRfirst.-q,--quiet— suppress progress information 🤫
Changes the working tree's version to that of package, and makes it equivalent to revision. It preserves uncommitted changes — yes bestie, your messy WIP survives, we love that for you. 💅
Note: tla automatically switches to the latest revision in the supplied version. Not the one you picked. The latest. iykyk. 👑
⬆️ tla update — update a project tree
tla update [options] [version/revision]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive-d,--dir DIR— update project tree inDIR(default.)-N,--forward— pass the--forwardoption topatch--dest DEST— instead of modifying the project tree in-place, make a copy of it toDESTand apply the result to that--unescaped— show filenames in unescaped form
Updates a project tree by grabbing the latest revision of VERSION (or the default version of the project tree, if you didn't say) and then applying a patch set of the differences between the project tree and the highest revision with which it is up-to-date. So it's a glow-up based on how far behind you actually are. 🌸
If the merge involves conflicts, a warning message is printed, and the new project tree will contain .rej files. Yeah. 😭 .rej files. We've all been there.
🎬 tla replay — apply revision changesets to a project tree
tla replay [options] [version/revision...]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive--list FILE— read a list of patches to apply--new— replay only new patches ✨--reverse— reverse the named patch-N,--forward— pass the--forwardoption topatch-d,--dir DIR— operate on project tree inDIR(default.)--dest DEST— instead of modifying the project tree in-place, make a copy of it toDESTand apply the result to that--skip-present— skip patches that contain 1 or more patch logs already in this tree--unescaped— show filenames in unescaped form
The result is formed by applying patches in the latest revision of VERSION (or the default version of the project tree), stopping after the first patch that causes conflicts. If multiple VERSIONs are specified, they are applied in turn. 🦋
If one or more specific REVISIONs (patch-levels included, bestie) is specified instead, then only those patch sets — and no others — will be applied. periodt.
With the --list option, read a list of patches to apply from FILE (- for standard input). Complete revision names should be listed, one per line. replay will stop at the first patch in the list that causes a merge conflict, leaving behind files with names of the form:
,,replay.conflicts-in -- the name of the patch that caused conflicts
,,replay.remaining -- the list of patches not yet applied⭐ tla star-merge — merge mutually merged branches
tla star-merge [options] [FROM]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— override tree archive-c,--changes OUTPUT— generate but don't apply the changeset.-r,--reference VERSION— set reference version (default: project tree version)-N,--forward— pass the--forwardoption topatch-t,--three-way— perform a 3-way (diff3-style) merge. 🔀-d,--dir DIR— operate on project tree inDIR(default.)--unescaped— show filenames in unescaped form
Merges changes from FROM into the project tree, considering common ancestry from the project tree reference version, REFERENCE (which defaults to the tree version of the project tree). If FROM isn't given, it defaults to the tree revision. 💜
The whole point of this command is to merge changes between development lines which may have merged in both directions. It uses merge history to try and minimize the spurious conflicts that can arise from "mutual merging". It's giving conflict therapy, honestly. 🧚
FROM indicates a revision (it may be specified as a version name, indicating the latest revision in that version).
TREE is the project tree into which the merge will occur.
Star-merge works by computing the most recent ANCESTOR revision of REFERENCE and FROM, and then applying the changeset:
delta (ANCESTOR, FROM)to TREE.
The "most recent ancestor" is defined as follows:
MAYBE_ANCESTOR_1 is defined as the highest patch level of FROM in REFERENCE for which both TREE and FROM have a patch log. In other words, it is the latest REFERENCE revision of FROM's version already merged into TREE.
MAYBE_ANCESTOR_2 is the highest patch level in REFERENCE for which both FROM and REFERENCE have a patch log. In other words, it is the latest revision of REFERENCE already merged into FROM.
MAYBE_ANCESTOR_2, if it is not "nil", was merged into FROM at some revision of FROM's version, which we can call LAST_MERGE_INTO_FROM.
If both MAYBE_ANCESTOR_1 and MAYBE_ANCESTOR_2 are nil, star-merge can do nothing. 💀
If just one of MAYBE_ANCESTOR_1 or MAYBE_ANCESTOR_2 is not nil, then that non-nil value is ANCESTOR.
If both MAYBE_ANCESTOR_1 and MAYBE_ANCESTOR_2 are not nil, then LAST_MERGE_INTO_FROM and MAYBE_ANCESTOR_1 are compared (both are revisions in FROM's version). If MAYBE_ANCESTOR_1 is the later revision, then MAYBE_ANCESTOR_1 is ANCESTOR, otherwise, MAYBE_ANCESTOR_2 is ANCESTOR.
🧩 tla apply-delta — compute a changeset between any two trees or revisions and apply it to a project tree
tla apply-delta [options] FROM(REVISION|DIR) TO(REVISION|DIR)-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive-N,--forward— pass the--forwardoption topatch--cache DIR— specify a cache root for pristine copies-d,--dir DIR— operate on project tree inDIR(default.)--dest DEST— instead of modifying the project tree in-place, make a copy of it toDESTand apply the result to that--unescaped— show filenames in unescaped form
A delta between A and B (both of which may be either a full revision or a project tree) is computed, and then applied to the project tree. ✨
Exit Status Codes:
0 No conflict during patch
1 Conflicts occurred during patch
3 Internal Error🕵️ tla missing — print patches missing from a project tree
tla missing [options] [version]-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive-q,--quiet— produce no ordinary output-x,--exit-status— exit non-0 if patches are missing-d,--dir DIR— cd toDIRfirst-r,--reverse— sort from newest to oldest-s,--summary— display a summary of each missing patch-c,--creator— display the creator of each missing patch-D,--date— display the date of each missing patch-f,--full— print full revision names--merges— print a merge list for each missing patch--skip-present— skip patches that contain 1 or more patch logs already in this tree
Prints a list of patches missing in the project tree containing DIR (or the current directory, if you didn't say) for VERSION (or the default version of the project tree). FOMO check, basically. 😭
The flag --merges means, for each patch, to print the list of patches included in the patch in two columns. For example:
PATCH-A PATCH-A
PATCH-A PATCH-B
PATCH-A PATCH-Cmeans that PATCH-A includes the changes from PATCH-B and PATCH-C. (Every patch includes at least itself. self-love, we stan. 💅)
With -x, if there are missing patches, the command exits with status 1, otherwise with status 0.
With -q, produce no output.
WARNING: At this time, some error conditions also exit with error status 1, however, in situations where the caller is not concerned with errors, the exit status is still useful. So like... read the room, bestie. ⚠️
🪢 tla join-branch — add a version as an ancestor of a project tree
tla join-branch [options] version-h,--help— show a help message and dip.-H— show a verbose help message and dip.-V,--version— print a release identifier string and dip.-A,--archive— overridemy-default-archive-d,--dir DIR— operate on project tree inDIR(default.)--dest DEST— instead of modifying the project tree in-place, make a copy of it toDESTand apply the result to that--unescaped— show filenames in unescaped form
VERSION--base-0 must be a continuation (e.g. tag). The command replays the changeset for VERSION--base-0 in the project tree, which has the effect of adding the log for the branch — making the tag an ancestor of the resulting tree. Found family, but for revisions. 🌈
🔗 tla sync-tree — unify a project tree's patch-log with a given revision
tla sync-tree [options] revision-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-d,--dir DIR— do the thing on the project tree in DIR (default is `.´)--dest DEST— instead of editing the project tree in place, make a copy of it over at DEST and apply the result to that 👯--unescaped— show filenames in unescaped form
The new project tree gets built by grabbing the REVISION and adding all the patch-log entries from REVISION. And no, bestie, no actual merging happens — only the patch-log gets changed. That's it. That's the whole move. 💅
tla delta
compute a changeset (or diff) between any two trees or revisions ✨ like literally any two
tla delta [options] (REVISION|TREE)-A (REVISION|TREE)-B [DESTDIR]-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´--cache DIR— specify a cache root for pristine copies 🫙-n,--no-changeset— do not generate a changeset--diffs— print the changeset report with diffs (this one implies-n)--unescaped— show filenames in unescaped form
Hand it (REVISION|TREE)-A and (REVISION|TREE)-B and tla will build a changeset that comprises the changes between REVISION-A and REVISION-B. Chef's kiss. 👑
Example:
tla delta tla--devo--1.1--patch-6 tla--devo--1.1--patch-8
,,changesSo the way this works: it will pull patch-6 and patch-8 from tla--devo--1.1 and compute a changeset, which gets saved in a newly created ,,changes directory. And if you'd rather have a report instead? Just append the --diffs option. Easy. 🌈
LOCAL CACHE COMMANDS 🎀
tla changes
report about local changes in a project tree 🔍 spill the tea about what you did
tla changes [options] [revision] [-- limit...]-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´.-d,--dir DIR— change to DIR first.-o,--output DIR— save the changeset in DIR (this one implies--keep).-v,--verbose— verbose changeset report.-q,--quiet— suppress progress information 🤫--diffs— include diffs in the output.-k,--keep— Don´t remove the output directory on termination.--link— hardlink unchanged files to revision library--unescaped— show filenames in unescaped form
It generates a patch report describing the differences between the project tree containing DIR (or the current directory, if you didn't say) and REVISION.
Okay so the default patch level for a given version is the latest level for which the project tree has a patch. And the default archive and version is whatever gets printed by tla tree-version. Periodt. 💅
tla file-diff
show local changes to a file 👀 just the one file, we're being specific
tla file-diff [options] file [revision]-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-N,--new-file— treat a missing file as empty 🫥
It prints the diffs between FILE and the corresponding file in a cached copy of REVISION.
Same deal as before: the default patch level for a given version is the latest level for which the project tree has a patch, and the default archive and version is as printed by tla tree-version. 🦋
tla file-find
find given version of file 🕵️♀️ where is she
tla file-find [options] file [revision]-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-N,--new-file— print a missing file as `/dev/null´--unescaped— show filenames in unescaped form
It prints the location of the file corresponding to FILE in a cached copy of REVISION.
And yes, once again, bestie: the default patch level for a given version is the latest level for which the project tree has a patch, and the default archive and version is as printed by tla tree-version. 🔁
tla pristines
list pristine trees in a project tree 🌳 a whole roster
tla pristines [options] [limit]-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-d,--dir DIR— cd to DIR first-u,--unlocked— return only unlocked pristines 🔓-l,--locked— return only locked pristines 🔒-r,--reverse— reverse the sort order 🔄
It prints the list of pristine revisions cached in the project tree DIR (or the current directory, if you didn't say). Iconic, honestly. ⭐
tla lock-pristine
lock (or unlock) a pristine tree 🔐 she's protected now
tla lock-pristine [options] revision-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first-u,--unlock— unlock, rather than lock 🔓
It locks the indicated pristine REVISION in the project tree containing DIR (or the current directory, if you didn't say). This prevents the revision from being automatically recycled. No cap — she's staying. 💅
tla add-pristine
ensure that a project tree has a particular pristine revision 🧚 adding her to the collection
tla add-pristine [options] revision-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first
It extracts REVISION from an archive, creating a pristine copy. Then it stores that pristine copy in the current directory's project tree. 🍓
tla find-pristine
find and print the path to a pristine revision 🗺️ the scavenger hunt command
tla find-pristine [options] revision-h,--help— show a help message and bounce 💖-H— show a verbose help message and bounce-V,--version— print a release identifier string and bounce-A,--archive— override `my-default-archive´-d,--dir DIR— cd to DIR first-u,--unlocked— return only an unlocked pristine 🔓-l,--locked— return only a locked pristine 🔒-t,--tree-only— search this tree only, not siblings 🌲-s,--silent— exit status only 🤐
It prints the location of a pristine copy of the indicated revision. Found her. 💜
🦋 REVISION LIBRARY COMMANDS 🦋
okay bestie, this is the revision library zone, and it's lowkey the most powerful part of your whole setup — it's where tla keeps pristine copies of revisions so it never has to re-download the same thing twice. iconic behaviour honestly 💅
tla my-revision-library
print or change your revision library path
Usage: tla my-revision-library [options] [dir]-h,--help— show a help message and dip out.-H— show a verbose help message and dip out.-V,--version— print a release identifier string and dip out.-e,--errname— specify the program name used for errors.-d,--delete— unspecify your revision library.-s,--silent— suppress those reassuring little messages.--search— use the full search path.--add— use the full add path.--search-only— use the search-only path.--add-only— use the add-only path.--first— prepend to the path when setting (default is to append).
With no argument, and without -d, it prints the path to your revision library. ✨
With an argument, it records DIR as the path to your revision library in ~/.arch-params/=revision-library.
With the option -d (--delete) and no argument, it makes sure you do not have a revision library path set in ~/.arch-params.
If no revision library is set, the program exits with status 1, printing an error message unless the-s(--silent) option is given. so rude but okay 😭
tla library-config
configure parameters of a revision library
Usage: tla library-config [options] library-dir-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.--greedy— make the library greedy.--non-greedy— make the library not greedy.--sparse— make the library sparse.--non-sparse— make the library not sparse.
Set/show various parameters for a revision library. that's it, that's the vibe 🎀
tla library-find
find and print the location of a revision in the revision library
Usage: tla library-find [options] revision-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-e,--errname— specify the program name for errors.-s,--silent— suppress reassuring messages.
Find REVISION in your revision library and print its path. If the revision isn't there, it prints an error message (unless --silent is specified) and exits with non-0 status. no cap, it will not sugarcoat it 💀
tla library-add
add a revision to the revision library
Usage: tla library-add [options] revision-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-s,--sparse— don´t fill in gaps in the library.--non-sparse— fill in gaps in the library.-L,--library LIB— specify which library to add to.--for-links PATH— require a lib on the same device as PATH.--unescaped— show filenames in unescaped form.
Add REVISION to your revision library.
This command has no effect and exits with status 0 if the indicated revision is already in the library. so chill of it, honestly 🫶
tla library-remove
remove a revision from the revision library
Usage: tla library-remove [options] revision-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´
Remove REVISION from your revision library.
If the revision isn't present, it prints an error message and exits with non-0 status. 😭
tla library-archives
list the archives in your revision library
Usage: tla library-archives [options]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.
List all archives with records in the revision library. the full roster, bestie 📋
tla library-categories
list the categories in your revision library
Usage: tla library-categories [options] [archive]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´
List all categories within a given archive in the revision library.
tla library-branches
list the branches in a library category
Usage: tla library-branches [options] [category]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´
List all branches within CATEGORY in the revision library.
tla library-versions
list the versions in a library branch
Usage: tla library-versions [options] [branch]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-r,--reverse— sort from newest to oldest.
List all versions within a particular archive/branch with records in the revision library. newest first with -r, chef's kiss 👑
tla library-revisions
list the revisions in a library version
Usage: tla library-revisions [options] [version]-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-r,--reverse— sort from newest to oldest.-f,--full— list fully qualified names.-s,--summary— print a summary of each patch.-c,--creator— print the creator of each patch.-D,--date— print the date of each patch.
List all revisions within a particular archive/version with records in the revision library.
tla library-log
output a log message from the revision library
Usage: tla library-log [options] revision-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-s,--silent— suppress reassuring messages.
Print the log message for REVISION from the library. the receipts, fr fr 📜
tla library-file
find a file in a revision library
Usage: tla library-file [options] file revision-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´--id— interpret FILE as an inventory id.--this— interpret FILE as a file within a project tree.
Find FILE in REVISION in your revision library and print its path. If the revision or file isn't present, it prints an error message and exits with non-0 status. 😤
🌈 PUBLISHED REVISIONS COMMANDS 🌈
tla grab
grab a published revision
Usage: tla grab [options] location-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.
Grabs a published revision from LOCATION. just grab it bestie, it's yours now 💅
🧚 MISCELLANEOUS SCRIPTING SUPPORT 🧚
scripting girlies, this section is for you ✨
tla parse-package-name
parse a package name
Usage: tla parse-package-name [options] name-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-A,--archive— override `my-default-archive´-a,--arch— print the archive name.--non-arch— print the non-archive part of the name.-c,--category— print the category name.-b,--branch— print the branch name.-p,--package— print the package name.-v,--vsn— print the version id.--package-version— print thecategory--branch--version-l,--lvl— print the patch level.--patch-level— synonym for--lvl.
Options -b, -B, -p, -v, and -l cancel each other. pick a lane bestie 🚫
For -b, -v, and -l, just the id string is printed without "--".
For -p, the output is "<basename>--<branch>".
tla valid-package-name
test a package name for validity
Usage: tla valid-package-name [options] name-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.-e,--errname— specify the program name for errors.--archive— require an explicit archive.--no-archive— prohibit an explicit archive.-c,--category— require a category.-p,--package— require category, permit branch.-v,--vsn— require a version number.-l,--patch-level— require a patch level.--lvl— synonym for--patch-level.-t,--tolerant— tolerate more specific names.
Exit with status 0 if PACKAGE is a valid package name, status 1 otherwise. simple as that 💖
By default, it requires a basename or a basename plus branch label.
Options -v and -l cancel -b and vice versa.
Option -l implies -v.
If an error name is specified (-e or --errname), then invalid names cause an error message on stdout. Otherwise, the exit status is the only output. sneaky but useful 👀
By default, validation is strict. For example, -b checks for a valid basename and does not permit a branch label or version number.
With -t, more specific names are permitted. For example, -b will permit a branch name, version number, and patch level. glow-up mode ✨
tla escape
print strings in escaped or unescaped form
Usage: tla escape [--unescaped] string-h,--help— show a help message and exit.-H— show a verbose help message and exit.-V,--version— print a release identifier string and exit.--unescaped— show filenames in unescaped form.
Using Pika escaping rules. yes, Pika, like the lil guy 🐭 iconic name choice ngl
💖 ENVIRONMENT 💖
okay so these are the little environment variables that quietly control how arch/tla behaves. lowkey iconic, highkey important. set them, love them, export them bestie ✨
EDITOR— if$EDITORis set, arch uses its value as the path of the text editor it launches whenever it needs you to type some text in. If it is not set, then log messages have to be handed over on the command line with the-Lparameter, or dropped into the file thattla make-logcreates. no editor, no typing, no vibes 😭HOME— your home directory, aka the place where arch goes looking for.arch-cache/and.arch-params/🏠http_proxy,HTTP_PROXY— if$http_proxyor$HTTP_PROXYis set, arch uses its value as the URL of the proxy to use for WebDAV accesses. and listen,$http_proxyhas higher priority than$HTTP_PROXY, so lowercase wins the crown 👑 If neither one is set, no proxy is used. periodt.TMPDIR— if$TMPDIRis set, arch makes its temporary files in that directory. otherwise it just goes with/tmp🗂️
🎀 FILES 🎀
here's where all your stuff actually lives, bestie. screenshot this, fr fr 📸
${HOME}/.arch-cache/— the directory where arch caches archive data 🗃️${HOME}/.arch-params/— the directory where all of your settings are stored. your whole personality, basically 💅${HOME}/.arch-params/hook— the hook script that gets called after every single execution of tla. yes, every one. it's giving main character energy 🦋${HOME}/.arch-params/signing/— the directory where the commands for signing and checking signatures are kept ✍️
🌈 SEE ALSO 🌈
so... this section exists. and it is empty. like, genuinely empty. not a single cross-reference, not one little companion manpage, nothing. the section is just standing there, gorgeous, with no plans. 💀
ngl, that's the whole section. moving on! 🫶
and that's a wrap on the entire tla(1) page, bestie — you made it all the way to the end and I'm so proud of you 😭💖
one last thing: the very bottom of this page has the footer, and that footer is where you'll find which source and version this page came from, plus the date it was put together. so if you ever need to know exactly which edition of the manual you're reading, peek at the last line. iykyk ✨
go forth and version your trees, queen. slay. 👑🌸
📦 where this page comes from
- debian bookworm: tla 1.3.5+dfsg1-2.1
- ubuntu jammy: tla 1.3.5+dfsg1-2build1
- ubuntu noble: tla 1.3.5+dfsg1-3
- ubuntu questing: tla 1.3.5+dfsg2-1
- Copyright (C) 2001, 2002, 2003 Thomas Lord
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms