1tla(1)                          tla arch client                         tla(1)
2
3
4

NAME

6       tla - arch command line client tool
7

SYNOPSIS

9       tla command [ command_options ]
10       tla command [-h|--help|-H]
11       tla [-h|--help|-H|-V|--version]
12

DESCRIPTION

14       tla is an implementation of arch .
15
16       arch is a version control system, which allows you to keep old versions
17       of files and directories (usually source code),  keep  a  log  of  who,
18       when, and why changes occurred, etc., like SVN, CVS, or RCS.
19
20       arch  has  a  number of advantages compared to competing systems. Among
21       these are:
22
23
24   Works on Whole Trees
25       arch keeps track of whole trees --  not  just  individual  files.   For
26       example,  if  you  change  many files in a tree, arch can record all of
27       those changes as a group rather than file-by-file; if you rename  files
28       or  reorganize  a  tree,  arch can record those tree arrangements along
29       with your changes to file contents.
30
31
32   Changeset Oriented
33       arch doesn´t simply "snapshot" your project trees.  Instead, arch asso‐
34       ciates  each  revision  with  a  particular changeset: a description of
35       exactly what has changed.  arch provides changeset oriented commands to
36       help you review changesets, merge trees by applying changesets, examine
37       the history of a tree by asking what changesets have  been  applied  to
38       it, and so forth.
39
40
41   Fully Distributed
42       arch  doesn´t  rely  on a central repository.  For example, there is no
43       need to give write access to a project´s  archive  to  all  significant
44       contributors.  Instead, each contributor can have their own archive for
45       their work.  arch seamlessly operates across archive boundaries.
46

COMMAND OVERVIEW

48   Help
49       tla help [options]
50              provide help with arch
51
52
53   User Commands
54       tla my-id [options] [id]
55              print or change your id
56
57
58       tla my-default-archive [options] [archive]
59              print or change your default archive
60
61
62       tla register-archive [options] [archive] location
63              change an archive location registration
64
65
66       tla archive-register [options] [archive] location
67              change an archive location registration
68
69
70       tla whereis-archive [options] archive
71              print an archive location registration
72
73
74       tla archives [options] [search regular expression]
75              report registered archives and their locations
76
77
78   Project Tree Commands
79       tla init-tree [options] [[archive]/version]
80              initialize a new project tree
81
82
83       tla tree-root [options] [dir]
84              find and print the root of a project tree
85
86
87       tla tree-version [options] [dir]
88              print the default version for a project tree
89
90
91       tla tree-id [options] [dir]
92              Print the tree identifier for a project tree
93
94
95       tla tree-revision [options] [dir]
96              Print the tree identifier for a project tree
97
98
99       tla set-tree-version [options] [archive]/version
100              set the default version for a project tree
101
102
103       tla undo [options] [revision] [-- file ...]
104              undo and save changes in a project tree
105
106
107       tla redo [options] [changeset]
108              redo changes in project tree
109
110
111       tla changes [options] [revision] [-- limit...]
112              report about local changes in a project tree
113
114
115       tla file-diff [options] file [revision]
116              show local changes to a file
117
118
119       tla diff [options] [revision] [-- files...]
120              report about local changes in a project tree
121
122
123       tla export [options] [revision] dir
124              export all or some of a tree revision
125
126
127   Project Tree Inventory Commands
128       tla inventory [options] [--] [dir]*
129              inventory a source tree
130
131
132       tla tree-lint [options] [dir]
133              audit a source tree
134
135
136       tla lint [options] [dir]
137              audit a source tree
138
139
140       tla id [options] file ...
141              report the inventory id for a file
142
143
144       tla id-tagging-method [options] [method]
145              print or change a project tree id tagging method
146
147
148       tla add [options] file ...
149              add an explicit inventory id
150
151
152       tla add-id [options] file ...
153              add an explicit inventory id
154
155
156       tla delete-id [options] file ...
157              remove an explicit inventory id
158
159
160       tla move-id [options] from to
161              move an explicit inventory id
162
163
164       tla touch [options] file ...
165              add an explicit inventory id, touching the file.
166
167
168       tla rm [options] file...
169              remove a file (or dir, or symlink) and  its  explicit  inventory
170              tag
171
172
173       tla mv [options] from to   OR   from1 from2 ... dir
174              move a file (or dir, or symlink) and its explicit inventory tag
175
176
177       tla explicit-default [options] [TAG-PREFIX]
178              print or modify default ids
179
180
181       tla default-id [options] [TAG-PREFIX]
182              print or modify default ids
183
184
185       tla id-tagging-defaults [options]
186              print the default =tagging-method contents
187
188
189   Patch Set Commands
190       tla changeset [options] ORIG MOD DEST [files]
191              compute a whole-tree changeset
192
193
194       tla mkpatch [options] ORIG MOD DEST [files]
195              compute a whole-tree changeset
196
197
198       tla apply-changeset [options] CHANGESET [TARGET]
199              apply a whole-tree changeset
200
201
202       tla dopatch [options] CHANGESET [TARGET]
203              apply a whole-tree changeset
204
205
206       tla show-changeset [options] [dir]
207              generate a report from a changeset
208
209
210   Archive Transaction Commands
211       tla make-archive [options] name location
212              create a new archive directory
213
214
215       tla archive-create [options] name location
216              create a new archive directory
217
218
219       tla archive-setup [options] [version ...]
220              create new categories, branches and versions
221
222
223       tla make-category [options] category
224              create a new archive category
225
226
227       tla make-branch [options] branch
228              create a new archive branch
229
230
231       tla make-version [options] version
232              create a new archive version
233
234
235       tla import [options] [[archive]/version]
236              archive a full-source base-0 revision
237
238
239       tla commit [options] [[archive]/version] [-- file ...]
240              archive a changeset-based revision
241
242
243       tla get [options] revision [dir]
244              construct a project tree for a revision
245
246
247       tla get-changeset [options] revision [dir]
248              retrieve a changeset from an archive
249
250
251       tla lock-revision [options] revision
252              lock (or unlock) an archive revision
253
254
255       tla archive-mirror [options] [from [to] [limit]]
256              update an archive mirror
257
258
259   Archive Commands
260       tla abrowse [options] [limit]
261              print an outline describing archive contents
262
263
264       tla rbrowse [options] [[ARCHIVE_NAME/]LIMIT_REGEX]
265              print an outline describing an archive´s contents
266
267
268       tla categories [options] [archive]
269              list the categories in an archive
270
271
272       tla branches [options] [category]
273              list the branches in an archive category
274
275
276       tla versions [options] [branch]
277              list the versions in an archive branch
278
279
280       tla revisions [options] [version]
281              list the revisions in an archive version
282
283
284       tla ancestry [options] [revision]
285              display the ancestory of a revision
286
287
288       tla ancestry-graph [options] [revision]
289              display the ancestory of a revision
290
291
292       tla cat-archive-log [options] revision
293              print the contents of an archived log entry
294
295
296       tla cacherev [options] [revision]
297              cache a full source tree in an archive
298
299
300       tla cachedrevs [options] [version]
301              list cached revisions in an archive
302
303
304       tla uncacherev [options] revision [dir]
305              remove a cached full source tree from an archive
306
307
308       tla archive-meta-info [options] item-name
309              report meta-info from an archive
310
311
312       tla archive-snapshot [options] dir [limit]
313              update an archive snapshot
314
315
316       tla archive-version [options]
317              list the archive-version in an archive
318
319
320       tla archive-fixup [options]
321              fix ancillary files in an archive
322
323
324   Patch Log Commands
325       tla make-log [options] [version]
326              initialize a new log file entry
327
328
329       tla log-versions [options]
330              list patch log versions in a project tree
331
332
333       tla add-log-version [options] [archive]/version
334              add a patch log version to a project tree
335
336
337       tla remove-log-version [options] [archive]/version
338              remove a version´s patch log from a project tree
339
340
341       tla logs [options] [[archive]/version ...]
342              list patch logs for a version in a project tree
343
344
345       tla cat-log [options] revision-spec
346              print the contents of a project tree log entry
347
348
349       tla changelog [options] [[archive]/version]
350              generate a ChangeLog from a patch log
351
352
353       tla log-for-merge [options] [[archive]/version]
354              generate a log entry body for a merge
355
356
357       tla merges [options] INTO [FROM]
358              report where two branches have been merged
359
360
361       tla new-merges [options] [[archive]/version]
362              list tree patches new to a version
363
364
365   Multi-project Configuration Commands
366       tla build-config [options] config
367              instantiate a multi-project config
368
369
370       tla cat-config [options] config
371              output information about a multi-project config
372
373
374   Commands for Branching and Merging
375       tla tag [options] SOURCE-REVISION TAG-VERSION
376              create a continuation revision
377
378
379       tla branch [options] [SOURCE] BRANCH
380              create a continuation revision
381
382
383       tla switch [options] [package]
384              change the working trees version
385
386
387       tla update [options] [version/revision]
388              update a project tree
389
390
391       tla replay [options] [version/revision...]
392              apply revision changesets to a project tree
393
394
395       tla star-merge [options] [FROM]
396              merge mutually merged branches
397
398
399       tla apply-delta [options] FROM(REVISION|DIR) TO(REVISION|DIR)
400              compute a changeset between any two trees or revisions and apply
401              it to a project tree
402
403
404       tla missing [options] [version]
405              print patches missing from a project tree
406
407
408       tla join-branch [options] version
409              add a version as an ancestor of a project tree
410
411
412       tla sync-tree [options] revision
413              unify a project tree´s patch-log with a given revision
414
415
416       tla delta [options] (REVISION|TREE)-A (REVISION|TREE)-B [DESTDIR]
417              compute a changeset (or diff) between any two trees or revisions
418
419
420   Local Cache Commands
421       tla changes [options] [revision] [-- limit...]
422              report about local changes in a project tree
423
424
425       tla file-diff [options] file [revision]
426              show local changes to a file
427
428
429       tla file-find [options] file [revision]
430              find given version of file
431
432
433       tla pristines [options] [limit]
434              list pristine trees in a project tree
435
436
437       tla lock-pristine [options] revision
438              lock (or unlock) a pristine tree
439
440
441       tla add-pristine [options] revision
442              ensure that a project tree has a particular pristine revision
443
444
445       tla find-pristine [options] revision
446              find and print the path to a pristine revision
447
448
449   Revision Library Commands
450       tla my-revision-library [options] [dir]
451              print or change your revision library path
452
453
454       tla library-dir [options] [dir]
455              print or change your revision library path
456
457
458       tla library-config [options] library-dir
459              configure parameters of a revision library
460
461
462       tla library-find [options] revision
463              find and print the  location  of  a  revision  in  the  revision
464              library
465
466
467       tla library-add [options] revision
468              add a revision to the revision library
469
470
471       tla library-remove [options] revision
472              remove a revision from the revision library
473
474
475       tla library-archives [options]
476              list the archives in your revision library
477
478
479       tla library-categories [options] [archive]
480              list the categories in your revision library
481
482
483       tla library-branches [options] [category]
484              list the branches in a library category
485
486
487       tla library-versions [options] [branch]
488              list the versions in a library branch
489
490
491       tla library-revisions [options] [version]
492              list the revisions in a library version
493
494
495       tla library-log [options] revision
496              output a log message from the revision library
497
498
499       tla library-file [options] file revision
500              find a file in a revision library
501
502
503   Published Revisions Commands
504       tla grab [options] location
505              grab a published revision
506
507
508   Miscellaneous Scripting Support
509       tla parse-package-name [options] name
510              parse a package name
511
512
513       tla valid-package-name [options] name
514              test a package name for validity
515
516
517       tla escape [--unescaped] string
518              print strings in escaped or unescaped form
519
520

HELP

522   tla help
523       provide help with arch
524
525       Usage: tla help [options]
526
527         -h, --help     Display a help message and exit.
528         -H             Display a verbose help message and exit.
529         -b, --basic    Display basic commands only
530         -V, --version  Display a release identifier string
531                        and exit.
532
533
534
535       This command prints a list of the available commands.
536
537
538       To see just a list of the options to a particular command, use:
539
540           tla $cmd -h
541
542
543       (where  $cmd  is the name of the command).   For additional explanation
544       about a given command, use:
545
546           tla $cmd -H
547
548
549

USER COMMANDS

551   tla my-id
552       print or change your id
553
554       Usage: tla my-id [options] [id]
555
556         -h, --help     Display a help message and exit.
557         -H             Display a verbose help message and exit.
558         -V, --version  Display a release identifier string
559                        and exit.
560         -e, --errname  specify program name for errors
561         -u, --uid      print only the UID portion of the ID
562
563
564       With no argument print your arch id.
565
566
567       With an argument, record ID-STRING as your id in ~/.arch-params/=id
568
569
570       Your id is recorded in various archives and log  messages  as  you  use
571       arch.   It must consist entirely of printable characters and fit on one
572       line.  By convention, it should have the form of an email  address,  as
573       in this example:
574
575               Jane Hacker <jane.hacker@gnu.org>
576
577
578       The  portion  of an id string between < and > is called your uid.  arch
579       sometimes uses your uid as  a  fragment  when  generating  unique  file
580       names.
581
582
583       The  option -u (--uid) causes only the uid part of your id string to be
584       printed.
585
586
587   tla my-default-archive
588       print or change your default archive
589
590       Usage: tla my-default-archive [options] [archive]
591
592         -h, --help     Display a help message and exit.
593         -H             Display a verbose help message and exit.
594         -V, --version  Display a release identifier string
595                        and exit.
596         -A, --archive  Override `my-default-archive´
597         -e, --errname  specify program name for errors
598         -d, --delete   unspecify your default archive
599         -s, --silent   suppress reassuring messages
600
601
602       With no argument, and without -d, print the name of  your  default  ar‐
603       chive.
604
605
606       With   an   argument,   record  ARCHIVE  as  your  default  archive  in
607       ~/.arch-params/=default-archive
608
609
610       With the option -d (--delete) and no argument, ensure that you  do  not
611       have a default archive set in ~/.arch-params.
612
613
614       Your default archive is determined this way:
615
616
617       If  the  option  -A (--archive) is given and not empty, that archive is
618       the default (which makes this script useful for processing a  -A  argu‐
619       ment that was passed to another script).
620
621
622       If  -A  is not given, but ~/.arch-params/=default-archive exists and is
623       not empty, that is your default archive.
624
625
626       Otherwise, your default archive is the name of the local archive rooted
627       at the argument to -R (--root) or specified in the environment variable
628       ARCHROOT.
629
630
631       If no default archive can be found by any of these means,  the  program
632       exits with status 1, printing an error message unless the -s (--silent)
633       option is given.
634
635
636   tla register-archive
637       change an archive location registration
638
639       Usage: tla register-archive [options] [archive] location
640
641         -h, --help        Display a help message and exit.
642         -H                Display a verbose help message and exit.
643         -V, --version     Display a release identifier string
644                           and exit.
645         -f, --force       overwrite existing location
646         --present-ok      return 0 even if archive exists
647         -d, --delete      delete archive registration
648
649
650       Record the location of ARCHIVE.
651
652
653       With -d, remove the registration of a  previously  registered  archive.
654       When  accompanied  by -f, override permissions on the registration file
655       and don´t complain if the archive is not registered.
656
657
658       A LOCATION should be either a directory name or a distant URL.
659
660
661       When registering a new archive, if no ARCHIVE´s name is passed  on  the
662       command  line,  then the archive´s name will be read automatically from
663       the archive´s meta data.
664
665
666       Archive locations are stored in ~/.arch-params/=locations.
667
668
669       You must register the location of a remote archive  before  you  access
670       it.   It  is  not strictly necessary to register the locations of local
671       archives (you can always specify  their  location  using  command  line
672       arguments  and/or environment variables), but registering local archive
673       locations is recommend (for simplicity).
674
675
676   tla archive-register
677       (alias for register-archive)
678
679       Usage: tla archive-register [options] [archive] location
680
681         -h, --help        Display a help message and exit.
682         -H                Display a verbose help message and exit.
683         -V, --version     Display a release identifier string
684                           and exit.
685         -f, --force       overwrite existing location
686         --present-ok      return 0 even if archive exists
687         -d, --delete      delete archive registration
688
689
690       Record the location of ARCHIVE.
691
692
693       With -d, remove the registration of a  previously  registered  archive.
694       When  accompanied  by -f, override permissions on the registration file
695       and don´t complain if the archive is not registered.
696
697
698       A LOCATION should be either a directory name or a distant URL.
699
700
701       When registering a new archive, if no ARCHIVE´s name is passed  on  the
702       command  line,  then the archive´s name will be read automatically from
703       the archive´s meta data.
704
705
706       Archive locations are stored in ~/.arch-params/=locations.
707
708
709       You must register the location of a remote archive  before  you  access
710       it.   It  is  not strictly necessary to register the locations of local
711       archives (you can always specify  their  location  using  command  line
712       arguments  and/or environment variables), but registering local archive
713       locations is recommend (for simplicity).
714
715
716   tla whereis-archive
717       print an archive location registration
718
719       Usage: tla whereis-archive [options] archive
720
721         -h, --help     Display a help message and exit.
722         -H             Display a verbose help message and exit.
723         -V, --version  Display a release identifier string
724                        and exit.
725
726
727       Print the registered location of an archive.
728
729
730       Usually the archive must have been previously registered with "tla reg‐
731       ister-archive".
732
733
734       As  a  special exception, the the archive is not registered, but is the
735       name of the archive rooted at the location given  with  the  option  -R
736       (--root)  or  in the environment variable ARCHROOT then print that root
737       directory.
738
739
740   tla archives
741       report registered archives and their locations
742
743       Usage: tla archives [options] [search regular expression]
744
745         -h, --help            Display a help message and exit.
746         -H                    Display a verbose help message and exit.
747         -V, --version         Display a release identifier string
748                               and exit.
749         -n, --names           print archive names only
750         -R, --exclude-remote  Exclude MIRROR and SOURCE archives.
751
752
753       Print a list of registered archives and their locations
754
755
756       If [search regex] is given then only archives  with  names  that  match
757       [search regex] will be shown
758
759

PROJECT TREE COMMANDS

761   tla init-tree
762       initialize a new project tree
763
764       Usage: tla init-tree [options] [[archive]/version]
765
766         -h, --help     Display a help message and exit.
767         -H             Display a verbose help message and exit.
768         -V, --version  Display a release identifier string
769                        and exit.
770         -A, --archive  Override `my-default-archive´
771         -d, --dir DIR  cd to DIR first
772         --nested       initialize a nested project tree.
773
774
775       Initialize DIR as a new project tree.
776
777
778       An  empty  patch-log  for  VERSION will be created, and VERSION will be
779       made the default location for check-ins.
780
781
782   tla tree-root
783       find and print the root of a project tree
784
785       Usage: tla tree-root [options] [dir]
786
787         -h, --help      Display a help message and exit.
788         -H              Display a verbose help message and exit.
789         -V, --version   Display a release identifier string
790                         and exit.
791         --accurate      error for mid-txn trees
792         -s, --silent    exit status only
793
794
795       Find and print the root of the project tree that contains DIR  (or  the
796       current  directory).  The option --accurate checks for three possibili‐
797       ties:
798
799           1) The project tree was the subject of a commit that
800              was killed before the log entry was added to the
801              tree´s patch log.  It is unknown whether or not
802              the commit took place in the archive.  The {arch}
803              directory contains the log file as "++mid-commit".
804
805           2) The project tree was the subject of a killed commit, but
806              it is certain the commit took place.  The log file
807              is stored as "++commit-definite".
808
809           3) The project tree patch log is fully up-to-date (as far as
810              arch knows).
811
812
813       In case 1, exit with an error and error message.
814
815
816       In case 2, install the log file before printing the tree root and exit‐
817       ing normally.
818
819
820       In case 3, print the tree root and exit normally.
821
822
823   tla tree-version
824       print the default version for a project tree
825
826       Usage: tla tree-version [options] [dir]
827
828         -h, --help     Display a help message and exit.
829         -H             Display a verbose help message and exit.
830         -V, --version  Display a release identifier string
831                        and exit.
832
833
834       Print  the  default  version of project tree DIR (or the current direc‐
835       tory).
836
837
838   tla tree-id
839       Print the tree identifier for a project tree
840
841       Usage: tla tree-id [options] [dir]
842
843         -h, --help     Display a help message and exit.
844         -H             Display a verbose help message and exit.
845         -V, --version  Display a release identifier string
846                        and exit.
847
848
849       Print the patchset identifier that represents the current  tree->  I.e.
850       foo@example.com/demo--1.0--patch-4.  Defaults  to  the tree the current
851       directory is in.
852
853
854   tla tree-revision
855       Print the tree identifier for a project tree
856
857       Usage: tla tree-revision [options] [dir]
858
859         -h, --help     Display a help message and exit.
860         -H             Display a verbose help message and exit.
861         -V, --version  Display a release identifier string
862                        and exit.
863
864
865       Print the patchset identifier that represents the current  tree->  I.e.
866       foo@example.com/demo--1.0--patch-4.  Defaults  to  the tree the current
867       directory is in.
868
869
870   tla set-tree-version
871       set the default version for a project tree
872
873       Usage: tla set-tree-version [options] [archive]/version
874
875         -h, --help     Display a help message and exit.
876         -H             Display a verbose help message and exit.
877         -V, --version  Display a release identifier string
878                        and exit.
879         -A, --archive  Override `my-default-archive´
880         -d, --dir DIR  cd to DIR first
881
882
883       This operation sets the default version on which to check-in the source
884       tree DIR (default: the current directory) during a commit.
885
886
887       You  can  specify  the  archive for this version as an ordinary command
888       line argument (ARCHIVE/VERSION) or via -R, -A and  the  environment  as
889       usual (try "tla my-default-archive --help").
890
891
892   tla undo
893       undo and save changes in a project tree
894
895       Usage: tla undo [options] [revision] [-- file ...]
896
897         -h, --help              Display a help message and exit.
898         -H                      Display a verbose help message and exit.
899         -V, --version           Display a release identifier string
900                                 and exit.
901         -A, --archive           Override `my-default-archive´
902         -d, --dir DIR           cd to DIR first
903         -o, --output PATCH-DIR  save changeset in PATCH-DIR
904         -n, --no-output         do not save the changeset
905         -N, --forward           pass the --forward option to `patch´
906         -q, --quiet             no progress reports while computing changeset
907         -x, --exclude FILE      exclude FILE from the files to commit
908         --unescaped             show filenames in unescaped form
909
910
911       Compute a patch set describing the changes from REVISION to the project
912       tree containing DIR.  Save the  patch  in  PATCH-DIR  (which  must  not
913       already  exist) and apply the patch in reverse to the project tree con‐
914       taining DIR.
915
916
917       The effect is to remove local changes in the DIR project tree but  save
918       them in a convenient form.
919
920
921       If FILE (a list of file names) is specified, then only changes to those
922       files will be undone.
923
924
925       If REVISION is not specified, the latest ancestor of the  default  ver‐
926       sion of project tree is used.
927
928
929       If  REVISION  is  specified  as  a  VERSION, the latest ancestor of the
930       project tree in that VERSION is used.
931
932
933       If DIR is not specified, "." is assumed.
934
935
936       If PATCH-DIR is not specified, a temporary file-name  of  the  matching
937       ,,undo-* is used.
938
939
940       If --no-output is specified, the patch set is not saved.
941
942
943       See also "tla redo -H" and "tla changes -H".
944
945
946   tla redo
947       redo changes in project tree
948
949       Usage: tla redo [options] [changeset]
950
951         -h, --help       Display a help message and exit.
952         -H               Display a verbose help message and exit.
953         -V, --version    Display a release identifier string
954                          and exit.
955         -N, --forward    pass the --forward option to `patch´
956         -k, --keep       do not delete the patch
957         -q, --quiet      no progress reports while computing changeset
958         -d, --dir DIR    Operate on project tree in DIR (default `.´)
959         --unescaped      show filenames in unescaped form
960
961
962       Apply CHANGESET to the project tree and then delete CHANGESET.
963
964
965       If  CHANGESET is not specified, the highest numbered ,,undo-N directory
966       in the project tree root is used.
967
968
969       If --keep is given, the changeset directory is not deleted.
970
971
972       See also "tla undo --help" and "tla apply-changeset --help".
973
974
975   tla changes
976       report about local changes in a project tree
977
978       Usage: tla changes [options] [revision] [-- limit...]
979
980         -h, --help        Display a help message and exit.
981         -H                Display a verbose help message and exit.
982         -V, --version     Display a release identifier string and exit.
983         -A, --archive     Override `my-default-archive´.
984         -d, --dir DIR     Change to DIR first.
985         -o, --output DIR  Save changeset in DIR (implies --keep).
986         -v, --verbose     Verbose changeset report.
987         -q, --quiet       Suppress progress information
988         --diffs           Include diffs in the output.
989         -k, --keep        Don´t remove the output directory on termination.
990         --link            hardlink unchanged files to revision library
991         --unescaped       show filenames in unescaped form
992
993
994       Generate a patch report describing the differences between the  project
995       tree containing DIR (or the current directory) and REVISION.
996
997
998       The  default  patch  level  for a given version is the latest level for
999       which the project tree has a patch.  The default archive and version is
1000       as printed by "tla tree-version".
1001
1002
1003   tla file-diff
1004       show local changes to a file
1005
1006       Usage: tla file-diff [options] file [revision]
1007
1008         -h, --help      Display a help message and exit.
1009         -H              Display a verbose help message and exit.
1010         -V, --version   Display a release identifier string
1011                         and exit.
1012         -A, --archive   Override `my-default-archive´
1013         -N, --new-file  Treat missing file as empty
1014
1015
1016       Print diffs between FILE and the corresponding file in a cached copy of
1017       REVISION.
1018
1019
1020       The default patch level for a given version is  the  latest  level  for
1021       which the project tree has a patch.  The default archive and version is
1022       as printed by "tla tree-version".
1023
1024
1025   tla diff
1026       report about local changes in a project tree
1027
1028       Usage: tla diff [options] [revision] [-- files...]
1029
1030         -h, --help          Display a help message and exit.
1031         -H                  Display a verbose help message and exit.
1032         -V, --version       Display a release identifier string and exit.
1033         -A, --archive       Override `my-default-archive´.
1034         -d, --dir DIR       Change to DIR first.
1035         -o, --output DIR    Save changeset in DIR.
1036         -v, --verbose       Verbose changeset report.
1037         -q, --quiet         Suppress progress information
1038         -s, --summary       Do not include diffs in the output.
1039         -k, --keep          Don´t remove the output directory on termination.
1040         -L, --latest        compare against the  latest  revision  (HEAD)  in
1041       branch
1042         -x, --exclude FILE  exclude FILE from the files to commit
1043         --link              hardlink unchanged files to revision library
1044         --unescaped         show filenames in unescaped form
1045         --limit LIMITS      limit the diff to LIMITS
1046         -D, --diff-options  specify options for `diff´ (for display only)
1047
1048
1049       Generate  a patch report describing the differences between the project
1050       tree containing DIR (or the current directory) and REVISION.
1051
1052
1053       The default patch level for a given version is  the  latest  level  for
1054       which the project tree has a patch.  The default archive and version is
1055       as printed by "tla tree-version".
1056
1057
1058   tla export
1059       export all or some of a tree revision
1060
1061       Usage: tla export [options] [revision] dir
1062
1063         -d, --dir DIR  Change to DIR first.
1064         -h, --help     Display a help message and exit.
1065         -H             Display a verbose help message and exit.
1066         -V, --version  Display a release identifier string
1067                        and exit.
1068         -s, --silent   no output
1069
1070
1071       Extract REVISION from an archive, creating a new source  tree  with  no
1072       control information. Note if export the local tree revision, local mod‐
1073       ifications will not be included; the exported file will only be  copies
1074       in the repository
1075
1076
1077

PROJECT TREE INVENTORY COMMANDS

1079   tla inventory
1080       inventory a source tree
1081
1082       Usage: tla inventory [options] [--] [dir]*
1083
1084         -h, --help          display help
1085         -H                  Display a verbose help message and exit.
1086         -V, --version       display version info
1087
1088         -s, --source        list source files
1089         -p, --precious      list precious files
1090         -b, --backups       list backup files
1091         -j, --junk          list junk files
1092         -u, --unrecognized  list unrecognized files
1093         -t, --trees         list roots of nested trees
1094
1095         -d, --directories   list only directories
1096         -f, --files         list only non-directories
1097         -B, --both          list both dirs and files
1098         --kind              indicate file kinds
1099
1100         --all               include arch control files
1101         --nested            include nested trees
1102
1103         --ids               list with ids (source files only)
1104         --untagged          include files that are missing ids
1105
1106         --explicit          use explicit file ids
1107         --implicit          permit implicit file ids
1108         --tagline           permit tagline file ids
1109         --names             use name-based file ids
1110         --unescaped         show filenames in unescaped form
1111
1112
1113       With no arguments, print a human-readable inventory report.
1114
1115
1116       With  category  options  (--source  etc) limit the report to just those
1117       files.  With no other options, the report  includes  all  sections  and
1118       files.
1119
1120
1121       The options -d, -f, and -B cancel each other.
1122
1123
1124       If  a  directory is precious, junk, or unrecognized, only the directory
1125       name itself is printed -- its contents are not searched.
1126
1127
1128       Each command option implies the  corresponding  category  option  (e.g.
1129       "--source-command" implies "--source").  The exit status of the command
1130       is ignored.
1131
1132
1133   tla tree-lint
1134       (alias for lint)
1135
1136       Usage: tla tree-lint [options] [dir]
1137
1138         -h, --help                Display a help message and exit.
1139         -H                        Display a verbose help message and exit.
1140         -V, --version             Display a release identifier string
1141                                   and exit.
1142         -s, --broken-symlinks     Just list broken symlinks
1143         -u, --unrecognized-files  Just list files  violating  naming  conven‐
1144       tions
1145         -t, --untagged-files      Just list files lacking inventory ids
1146         -m, --missing-files       Just list inventory ids lacking correspond‐
1147       ing files
1148         -d, --duplicate-ids       Just list duplicated ids
1149         --strict                  exit with non-0 status on _any_ oddity
1150         --unescaped               show filenames in unescaped form
1151
1152
1153       Audit a source tree for missing files, untagged files,  duplicate  ids,
1154       and files not matching recognized naming conventions.
1155
1156
1157       The  default is to list files failing any of those tests.  Enabling any
1158       of the `specific´ tests disables the rest,  unless  they´re  explicitly
1159       enabled  on  the command line. Therefore, "tla tree-lint" is equivalent
1160       to "tla tree-lint -sutmd"
1161
1162   tla lint
1163       audit a source tree
1164
1165       Usage: tla lint [options] [dir]
1166
1167         -h, --help                Display a help message and exit.
1168         -H                        Display a verbose help message and exit.
1169         -V, --version             Display a release identifier string
1170                                   and exit.
1171         -s, --broken-symlinks     Just list broken symlinks
1172         -u, --unrecognized-files  Just list files  violating  naming  conven‐
1173       tions
1174         -t, --untagged-files      Just list files lacking inventory ids
1175         -m, --missing-files       Just list inventory ids lacking correspond‐
1176       ing files
1177         -d, --duplicate-ids       Just list duplicated ids
1178         --strict                  exit with non-0 status on _any_ oddity
1179         --unescaped               show filenames in unescaped form
1180
1181
1182       Audit a source tree for missing files, untagged files,  duplicate  ids,
1183       and files not matching recognized naming conventions.
1184
1185
1186       The  default is to list files failing any of those tests.  Enabling any
1187       of the `specific´ tests disables the rest,  unless  they´re  explicitly
1188       enabled  on  the command line. Therefore, "tla tree-lint" is equivalent
1189       to "tla tree-lint -sutmd"
1190
1191   tla id
1192       report the inventory id for a file
1193
1194       Usage: tla id [options] file ...
1195
1196         -h, --help       Display a help message and exit.
1197         -H               Display a verbose help message and exit.
1198         -V, --version    Display a release identifier string
1199                          and exit.
1200         --implicit       Use the implicit id tagging method.
1201         --tagline        Use the tagline id tagging method (default).
1202         --explicit       Use the explicit id tagging method.
1203         --names          Use the names id tagging method.
1204         --silent         No output -- exit status only.
1205         --unescaped      show filenames in unescaped form
1206
1207
1208       Print a file´s inventory id.
1209
1210
1211   tla id-tagging-method
1212       print or change a project tree id tagging method
1213
1214       Usage: tla id-tagging-method [options] [method]
1215
1216         -h, --help     Display a help message and exit.
1217         -H             Display a verbose help message and exit.
1218         -V, --version  Display a release identifier string
1219                        and exit.
1220         -d, --dir DIR  cd to DIR first
1221         --strict       exit with error if method not set
1222
1223
1224       Print or change the method by which source files are identified in  DIR
1225       (or the current directory).
1226
1227
1228       When setting, METHOD must be one of:
1229
1230               names           -- use naming conventions only
1231               implicit        -- use naming conventions but permit
1232                                  for inventory tags
1233               explicit        -- require explicit designation of source
1234               tagline         -- mix names, explicit and arch-tag: methods
1235
1236
1237       When  printing,  if  --strict  is  provided but no id tagging method is
1238       explicitly set, print an error.
1239
1240
1241   tla add
1242       (alias for add-id)
1243
1244       Usage: tla add [options] file ...
1245
1246         -h, --help           Display a help message and exit.
1247         -H                   Display a verbose help message and exit.
1248         -V, --version        Display a release identifier string
1249                              and exit.
1250         -s, --stop-on-error  stop adding further on error  (default  to  con‐
1251       tinue)
1252         -i, --id ID          Specify ID, instead of using auto-generated id.
1253
1254
1255       Create  an explicit inventory id for FILE (which may be a regular file,
1256       symbolic link, or directory).
1257
1258
1259   tla add-id
1260       add an explicit inventory id
1261
1262       Usage: tla add-id [options] file ...
1263
1264         -h, --help           Display a help message and exit.
1265         -H                   Display a verbose help message and exit.
1266         -V, --version        Display a release identifier string
1267                              and exit.
1268         -s, --stop-on-error  stop adding further on error  (default  to  con‐
1269       tinue)
1270         -i, --id ID          Specify ID, instead of using auto-generated id.
1271
1272
1273       Create  an explicit inventory id for FILE (which may be a regular file,
1274       symbolic link, or directory).
1275
1276
1277   tla delete-id
1278       remove an explicit inventory id
1279
1280       Usage: tla delete-id [options] file ...
1281
1282         -h, --help     Display a help message and exit.
1283         -H             Display a verbose help message and exit.
1284         -V, --version  Display a release identifier string
1285                        and exit.
1286
1287
1288       Remove an explicit inventory id for FILE (which may be a regular  file,
1289       symbolic link, or directory).
1290
1291
1292   tla move-id
1293       move an explicit inventory id
1294
1295       Usage: tla move-id [options] from to
1296
1297         -h, --help     Display a help message and exit.
1298         -H             Display a verbose help message and exit.
1299         -V, --version  Display a release identifier string
1300                        and exit.
1301
1302
1303       Move  an explicit inventory id for FILE (which may be a regular file or
1304       symbolic link but which must not be a directory).
1305
1306
1307   tla touch
1308       add an explicit inventory id, touching the file.
1309
1310       Usage: tla touch [options] file ...
1311
1312         -h, --help     Display a help message and exit.
1313         -H             Display a verbose help message and exit.
1314         -V, --version  Display a release identifier string
1315                        and exit.
1316         -i, --id ID    Specify ID, instead of using auto-generated id.
1317
1318
1319       Create an explicit inventory id for FILE (which may be a regular  file,
1320       symbolic  link,  or directory). This command also sets the modification
1321       and access times of the file, creating it if necessary.
1322
1323
1324   tla rm
1325       remove a file (or dir, or symlink) and its explicit inventory tag
1326
1327       Usage: tla rm [options] file...
1328
1329         -h, --help     Display a help message and exit.
1330         -H             Display a verbose help message and exit.
1331         -V, --version  Display a release identifier string
1332                        and exit.
1333
1334
1335       This command is suitable as a replacement for rm(1) within any tla tree
1336       for any remove operation, regardless of id tagging method.
1337
1338
1339   tla mv
1340       move a file (or dir, or symlink) and its explicit inventory tag
1341
1342       Usage: tla mv [options] from to   OR   from1 from2 ... dir
1343
1344         -h, --help     Display a help message and exit.
1345         -H             Display a verbose help message and exit.
1346         -V, --version  Display a release identifier string
1347                        and exit.
1348
1349
1350       This command is suitable as a replacement for mv(1) within any tla tree
1351       for any move operation, regardless of id tagging method.
1352
1353
1354   tla explicit-default
1355       print or modify default ids
1356
1357       Usage: tla explicit-default [options] [TAG-PREFIX]
1358
1359         -h, --help       Display a help message and exit.
1360         -H               Display a verbose help message and exit.
1361         -V, --version    Display a release identifier string
1362                          and exit.
1363         -D, --dir DIR    cd to DIR first
1364         -d, --delete     remove the default
1365         -s, --strong     use the strong default (default)
1366         -w, --weak       use the weak default
1367         --dont-care      use the dont-care default
1368
1369
1370       For files in this directory, use:
1371
1372            ID-PREFIX__BASENAME
1373
1374
1375       as the default explicit id for all files in this directory that do  not
1376       have an explicit explicit id.
1377
1378
1379       With no arguments, print the previously set ID-PREFIX.
1380
1381
1382       By  default, this command sets, prints or deletes a "strong default" --
1383       a default explicit id which overrides implicit ids.
1384
1385
1386       With --weak, set (or print) a weak default id which  is  overridden  by
1387       explicit ids.
1388
1389
1390       The --dont-care option sets (or with -d, clears) a flag for that direc‐
1391       tory that causes unidged files not to  be  reported  as  such  in  "tla
1392       tree-lint" reports.
1393
1394
1395   tla default-id
1396       (alias for explicit-default)
1397
1398       Usage: tla default-id [options] [TAG-PREFIX]
1399
1400         -h, --help       Display a help message and exit.
1401         -H               Display a verbose help message and exit.
1402         -V, --version    Display a release identifier string
1403                          and exit.
1404         -D, --dir DIR    cd to DIR first
1405         -d, --delete     remove the default
1406         -s, --strong     use the strong default (default)
1407         -w, --weak       use the weak default
1408         --dont-care      use the dont-care default
1409
1410
1411       For files in this directory, use:
1412
1413            ID-PREFIX__BASENAME
1414
1415
1416       as  the default explicit id for all files in this directory that do not
1417       have an explicit explicit id.
1418
1419
1420       With no arguments, print the previously set ID-PREFIX.
1421
1422
1423       By default, this command sets, prints or deletes a "strong default"  --
1424       a default explicit id which overrides implicit ids.
1425
1426
1427       With  --weak,  set  (or print) a weak default id which is overridden by
1428       explicit ids.
1429
1430
1431       The --dont-care option sets (or with -d, clears) a flag for that direc‐
1432       tory  that  causes  unidged  files  not  to be reported as such in "tla
1433       tree-lint" reports.
1434
1435
1436   tla id-tagging-defaults
1437       print the default =tagging-method contents
1438
1439       Usage: tla id-tagging-defaults [options]
1440
1441         -h, --help     Display a help message and exit.
1442         -H             Display a verbose help message and exit.
1443         -V, --version  Display a release identifier string
1444                        and exit.
1445
1446
1447       Print the boilerplate contents that are used to  initialize  new  =tag‐
1448       ging-method files.
1449
1450

PATCH SET COMMANDS

1452   tla changeset
1453       compute a whole-tree changeset
1454
1455       Usage: tla changeset [options] ORIG MOD DEST [files]
1456
1457         -h, --help             Display a help message and exit.
1458         -H                     Display a verbose help message and exit.
1459         -V, --version          Display a release identifier string
1460                                and exit.
1461         --file-list FILES      record only diffs of selected files
1462         --unescaped            show filenames in unescaped form
1463
1464
1465       Create the output directory DESTINATION (it must not already exist).
1466
1467
1468       Compare source trees ORIGINAL and MODIFIED.  Create a changeset tree in
1469       DESTINATION
1470
1471
1472       See also "tla apply-changeset -H".
1473
1474
1475   tla mkpatch
1476       (alias for changeset)
1477
1478       Usage: tla mkpatch [options] ORIG MOD DEST [files]
1479
1480         -h, --help             Display a help message and exit.
1481         -H                     Display a verbose help message and exit.
1482         -V, --version          Display a release identifier string
1483                                and exit.
1484         --file-list FILES      record only diffs of selected files
1485         --unescaped            show filenames in unescaped form
1486
1487
1488       Create the output directory DESTINATION (it must not already exist).
1489
1490
1491       Compare source trees ORIGINAL and MODIFIED.  Create a changeset tree in
1492       DESTINATION
1493
1494
1495       See also "tla apply-changeset -H".
1496
1497
1498   tla apply-changeset
1499       apply a whole-tree changeset
1500
1501       Usage: tla apply-changeset [options] CHANGESET [TARGET]
1502
1503         -h, --help       Display a help message and exit.
1504         -H               Display a verbose help message and exit.
1505         -V, --version    Display a release identifier string
1506                          and exit.
1507         -N, --forward    pass the --forward option to `patch´
1508         -r, --reverse    Apply the changeset in reverse
1509         --unescaped      show filenames in unescaped form
1510
1511
1512       Apply the changeset CHANGESET to the source tree TARGET (default `.´).
1513
1514
1515       See also "tla changeset -H".
1516
1517
1518   tla dopatch
1519       (alias for apply-changeset)
1520
1521       Usage: tla dopatch [options] CHANGESET [TARGET]
1522
1523         -h, --help       Display a help message and exit.
1524         -H               Display a verbose help message and exit.
1525         -V, --version    Display a release identifier string
1526                          and exit.
1527         -N, --forward    pass the --forward option to `patch´
1528         -r, --reverse    Apply the changeset in reverse
1529         --unescaped      show filenames in unescaped form
1530
1531
1532       Apply the changeset CHANGESET to the source tree TARGET (default `.´).
1533
1534
1535       See also "tla changeset -H".
1536
1537
1538   tla show-changeset
1539       generate a report from a changeset
1540
1541       Usage: tla show-changeset [options] [dir]
1542
1543         -h, --help       Display a help message and exit.
1544         -H               Display a verbose help message and exit.
1545         -V, --version    Display a release identifier string
1546                          and exit.
1547         --diffs          include diff output
1548         --unescaped      show filenames in unescaped form
1549
1550
1551       Produce a human-readable summary of a changeset.
1552
1553

ARCHIVE TRANSACTION COMMANDS

1555   tla make-archive
1556       create a new archive directory
1557
1558       Usage: tla make-archive [options] name location
1559
1560         -h, --help                       Display a help message and exit.
1561         -H                                Display  a verbose help message and
1562       exit.
1563         -V, --version                    Display a release identifier string
1564                                          and exit.
1565         -m, --mirror MASTER              create mirror of specified archive
1566         -M, --mirror-from MASTER-SOURCE  create pull-based mirror  of  speci‐
1567       fied archive
1568         -l,  --listing                     Keep  .listing files up-to-date in
1569       this archive.
1570         -t, --tla                        Create a tla format archive.
1571         -b, --baz                        Create a  baz  format  archive  (the
1572       default).
1573         -s,  --signed                      GPG  sign the contents of this ar‐
1574       chive.
1575
1576
1577       NAME is the global name for the archive.  It must be an  email  address
1578       with  a  fully qualified domain name, optionally followed by "--" and a
1579       string of letters, digits, periods and dashes.
1580
1581
1582       With --mirror, label the new archive as a mirror  of  MASTER.  Ordinary
1583       commits  can  not be made to a mirror archive, however the command "tla
1584       archive-mirror" can write to a mirror.
1585
1586
1587       Two special forms of this command are available:
1588
1589          tla make-archive --mirror MASTER LOCATION
1590
1591
1592       is equivalent to:
1593
1594          tla make-archive --mirror MASTER MASTER-MIRROR LOCATION
1595
1596
1597       and thus "tla archive-mirror MASTER" will push changes from  MASTER  to
1598       the newly created mirror.
1599
1600          tla make-archive --mirror-from MASTER-SOURCE LOCATION
1601
1602
1603       is equivalent to:
1604
1605          tla make-archive --mirror MASTER-SOURCE MASTER LOCATION
1606
1607
1608       and  thus  "tla  archive-mirror  MASTER"  will  pull  changes from MAS‐
1609       TER-SOURCE to the newly created mirror.
1610
1611
1612       The first of these two special forms is especially handy when  creating
1613       a remote mirror in which to publish a local repository.
1614
1615
1616       The  second  special  form  is  handy when creating a local mirror of a
1617       remote archive, locally bound to the remote archive´s name.
1618
1619
1620       The --tla option creates a tla format archive, the default is  to  cre‐
1621       ate a Bazaar archive.
1622
1623
1624
1625   tla archive-create
1626       (alias for make-archive)
1627
1628       Usage: tla archive-create [options] name location
1629
1630         -h, --help                       Display a help message and exit.
1631         -H                                Display  a verbose help message and
1632       exit.
1633         -V, --version                    Display a release identifier string
1634                                          and exit.
1635         -m, --mirror MASTER              create mirror of specified archive
1636         -M, --mirror-from MASTER-SOURCE  create pull-based mirror  of  speci‐
1637       fied archive
1638         -l,  --listing                     Keep  .listing files up-to-date in
1639       this archive.
1640         -t, --tla                        Create a tla format archive.
1641         -b, --baz                        Create a  baz  format  archive  (the
1642       default).
1643         -s,  --signed                      GPG  sign the contents of this ar‐
1644       chive.
1645
1646
1647       NAME is the global name for the archive.  It must be an  email  address
1648       with  a  fully qualified domain name, optionally followed by "--" and a
1649       string of letters, digits, periods and dashes.
1650
1651
1652       With --mirror, label the new archive as a mirror  of  MASTER.  Ordinary
1653       commits  can  not be made to a mirror archive, however the command "tla
1654       archive-mirror" can write to a mirror.
1655
1656
1657       Two special forms of this command are available:
1658
1659          tla make-archive --mirror MASTER LOCATION
1660
1661
1662       is equivalent to:
1663
1664          tla make-archive --mirror MASTER MASTER-MIRROR LOCATION
1665
1666
1667       and thus "tla archive-mirror MASTER" will push changes from  MASTER  to
1668       the newly created mirror.
1669
1670          tla make-archive --mirror-from MASTER-SOURCE LOCATION
1671
1672
1673       is equivalent to:
1674
1675          tla make-archive --mirror MASTER-SOURCE MASTER LOCATION
1676
1677
1678       and  thus  "tla  archive-mirror  MASTER"  will  pull  changes from MAS‐
1679       TER-SOURCE to the newly created mirror.
1680
1681
1682       The first of these two special forms is especially handy when  creating
1683       a remote mirror in which to publish a local repository.
1684
1685
1686       The  second  special  form  is  handy when creating a local mirror of a
1687       remote archive, locally bound to the remote archive´s name.
1688
1689
1690       The --tla option creates a tla format archive, the default is  to  cre‐
1691       ate a Bazaar archive.
1692
1693
1694
1695   tla archive-setup
1696       create new categories, branches and versions
1697
1698       Usage: tla archive-setup [options] [version ...]
1699
1700         -h, --help       Display a help message and exit.
1701         -H               Display a verbose help message and exit.
1702         -V, --version    Display a release identifier string
1703                          and exit.
1704         -A, --archive    Override `my-default-archive´
1705         -f, --file FILE  read the list of desired versions from FILE
1706         -b, --branches   make base-0 tags
1707         -c, --cache      archive cache when creating base-0 tags
1708
1709
1710       Given  a  list of categories, branches, and versions, ensure that these
1711       exist in the appropriate archive.
1712
1713
1714       For example, starting with an empty archive,:
1715
1716           % tla archive-setup  proja--devo--1.0 projb
1717
1718
1719       creates a category, branch, and version for project A, and  a  category
1720       for project B
1721
1722
1723       When  the  --file  option  is used, the list of items to create is read
1724       from a file (use "-" to indicate standard input).
1725
1726
1727       With the --file option, the option --branches may be provided.  In this
1728       case,  the  input should have two items per line:  a target version (to
1729       create), and a source version to build a tag from.   For example, given
1730       an input file containg:
1731
1732           proja--devo--1.0  his@foo.com/proja--devo--1.0
1733
1734
1735       with  --branches, archive-setup creates a proja version in your default
1736       archive, and adds a base-0 revision to that project which is a  tag  of
1737       the  latest revision in his@foo.com´s archive.  (This can make it quite
1738       easy to set-up a new archive which contains branches from existing  ar‐
1739       chives, for example.)
1740
1741
1742       If --branches is used, the --cache option may also be used.   It causes
1743       each new base-0 revision to be archive-cached (see "tla cacherev -H")
1744
1745
1746   tla make-category
1747       create a new archive category
1748
1749       Usage: tla make-category [options] category
1750
1751         -h, --help     Display a help message and exit.
1752         -H             Display a verbose help message and exit.
1753         -V, --version  Display a release identifier string
1754                        and exit.
1755         -A, --archive  Override `my-default-archive´
1756
1757
1758       Create CATEGORY as a category in the indicated  archive.  The  category
1759       must not already exist.
1760
1761
1762   tla make-branch
1763       create a new archive branch
1764
1765       Usage: tla make-branch [options] branch
1766
1767         -h, --help     Display a help message and exit.
1768         -H             Display a verbose help message and exit.
1769         -V, --version  Display a release identifier string
1770                        and exit.
1771         -A, --archive  Override `my-default-archive´
1772
1773
1774       Create BRANCH as a branch in the indicated archive.
1775
1776
1777       The category containing the branch must already exist.
1778
1779
1780   tla make-version
1781       create a new archive version
1782
1783       Usage: tla make-version [options] version
1784
1785         -h, --help     Display a help message and exit.
1786         -H             Display a verbose help message and exit.
1787         -V, --version  Display a release identifier string
1788                        and exit.
1789         -A, --archive  Override `my-default-archive´
1790
1791
1792       Create  VERSION  as  a version in the indicated archive. The branch for
1793       this version must not already exist.
1794
1795
1796   tla import
1797       archive a full-source base-0 revision
1798
1799       Usage: tla import [options] [[archive]/version]
1800
1801         -h, --help              Display a help message and exit.
1802         -H                      Display a verbose help message and exit.
1803         -V, --version           Display a release identifier string
1804                                 and exit.
1805         -A, --archive           Override `my-default-archive´.
1806         -d, --dir DIR           Change to DIR first.
1807         -l, --log FILE          Commit with log file FILE.
1808         -s, --summary TEXT      log with summary TEXT plus log-for-merge out‐
1809       put
1810         -L, --log-message TEXT  log with TEXT
1811         -S,  --setup             Use `archive-setup´ if necessary; implied by
1812       default.
1813         --no-setup              Do not use `archive-setup´ even if necessary.
1814         --unescaped             show filenames in unescaped form
1815
1816
1817       Archive a from-scratch base revision of the project tree containing DIR
1818       (or the current directory).  Use this command to create the first revi‐
1819       sion of a new project.
1820
1821
1822       If --log-message is specified without --summary, then TEXT is used both
1823       as the summary and the first line of the log body.
1824
1825
1826   tla commit
1827       archive a changeset-based revision
1828
1829       Usage: tla commit [options] [[archive]/version] [-- file ...]
1830
1831         -h,  --help                                Display a help message and
1832       exit.
1833         -H                                       Display a verbose help  mes‐
1834       sage and exit.
1835         -V, --version                            Display a release identifier
1836       string
1837                                                  and exit.
1838         -A,  --archive                             Override   `my-default-ar‐
1839       chive´
1840         -d, --dir DIR                            cd to DIR first
1841         -l, --log FILE                           commit with log file FILE
1842         -s,  --summary  TEXT                       log with summary TEXT plus
1843       log-for-merge output
1844         -L,  --log-message  TEXT                     log   with   TEXT   plus
1845       log-for-merge output
1846         -x,  --exclude FILE                       exclude FILE from the files
1847       to commit
1848         --strict                                 strict tree-lint
1849         --seal                                   create a version-0 revision
1850         --fix                                    create a versionfix revision
1851         --out-of-date-ok                         commit even if out of date
1852         --file-list FILE                         commit only changes to files
1853       listed in FILE
1854         --write-revision  REVISION_FILE_SPEC       write  the  new tree id to
1855       REVISION_FILE_SPEC before committing
1856         --unescaped                              show filenames in  unescaped
1857       form
1858
1859
1860       Archive  a  revision of the project tree containing DIR (or the current
1861       directory)
1862
1863
1864       If there are any automated ChangeLog files, update them before  comput‐
1865       ing the patch set.
1866
1867
1868       If --log-message is specified without --summary, then TEXT is used both
1869       as the summary and the first line of the log body.
1870
1871
1872   tla get
1873       construct a project tree for a revision
1874
1875       Usage: tla get [options] revision [dir]
1876
1877         -h, --help           Display a help message and exit.
1878         -H                   Display a verbose help message and exit.
1879         -V, --version        Display a release identifier string
1880                              and exit.
1881         -A, --archive        Override `my-default-archive´
1882         --cache DIR          cache root for trees with pristines
1883         --no-pristine        don´t save a pristine copy
1884         --link               hardlink files to revision  library  instead  of
1885       copying
1886         --library            ensure the revision is in a revision library
1887         --sparse             add library entries sparsely (--link, --library)
1888         --non-sparse         add library entries densely (--link, --library)
1889         -s, --silent         no output
1890         --no-greedy-add      do not allow greedy libraries to add revisions
1891         --unescaped          show filenames in unescaped form
1892
1893
1894       Extract  REVISION  from  an archive, creating the new project tree DIR.
1895       If DIR is not specified, store the working copy in  a  subdirectory  of
1896       the  current  directory,  giving  it the name of the revision. CAUTION:
1897       when using the links option be sure to use copy-on-write on your editor
1898       or the revision library will be corrupted. Either way, the project tree
1899       must not already exist.
1900
1901
1902   tla get-changeset
1903       retrieve a changeset from an archive
1904
1905       Usage: tla get-changeset [options] revision [dir]
1906
1907         -h, --help     Display a help message and exit.
1908         -H             Display a verbose help message and exit.
1909         -V, --version  Display a release identifier string
1910                        and exit.
1911         -A, --archive  Override `my-default-archive´
1912
1913
1914       Retrieve the changeset for REVISION and store it in the  directory  DIR
1915       (or a directory named REVISION.patches).  DIR must not already exist.
1916
1917
1918   tla lock-revision
1919       lock (or unlock) an archive revision
1920
1921       Usage: tla lock-revision [options] revision
1922
1923         -h, --help     Display a help message and exit.
1924         -H             Display a verbose help message and exit.
1925         -V, --version  Display a release identifier string
1926                        and exit.
1927         -A, --archive  Override `my-default-archive´
1928         -u, --unlock   release a lock owned by you
1929         -b, --break    break any existing lock
1930
1931
1932       Acquire the lock needed to create REVISION.
1933
1934
1935       Revision must be the next patch-level in sequence, however, if no patch
1936       level is specified, the lock is taken unconditionally. If no version is
1937       specified, the latest version is locked.
1938
1939
1940   tla archive-mirror
1941       update an archive mirror
1942
1943       Usage: tla archive-mirror [options] [from [to] [limit]]
1944
1945         -h, --help         Display a help message and exit.
1946         -H                 Display a verbose help message and exit.
1947         -V, --version      Display a release identifier string
1948                            and exit.
1949         --no-cached        don´t copy cached revisions
1950         -s, --summary      print the summary of each patch
1951         --cached-tags      copy only cachedrevs for tags to other archives
1952
1953
1954       If  no arguments are given, update your `my-default-archive´-MIRROR ar‐
1955       chive with the contents of `my-default-archive´.
1956
1957
1958       If a [FROM] archive is given, update the [FROM]-MIRROR archive with the
1959       contents of the [FROM] archive
1960
1961
1962       If  both  [FROM]  and [TO] archives are specified, update [TO] with the
1963       contents of [FROM]
1964
1965
1966       If LIMIT is provided, it should be  a  category,  branch,  version,  or
1967       revision  name.   Only the indicated part of FROM will be copied to TO.
1968       If LIMIT is a revision,  then  cached  revisions  will  be  copied  and
1969       deleted to TO.
1970
1971
1972       (see "tla make-archive -H".).
1973
1974

ARCHIVE COMMANDS

1976   tla abrowse
1977       print an outline describing archive contents
1978
1979       Usage: tla abrowse [options] [limit]
1980
1981         -h, --help             Display a help message and exit.
1982         -H                     Display a verbose help message and exit.
1983         -V, --version          Display a release identifier string
1984                                and exit.
1985         -A, --archive          Override `my-default-archive´
1986         -r, --reverse          sort revisions from newest to oldest
1987         -s, --summary          print a summary of each patch
1988         -c, --creator          print the creator of each patch
1989         -D, --date             print the date of each patch
1990         -k,  --kind             show each revision kind (import, changeset or
1991       id)
1992         -C, --cacherevs        show cached revisions
1993         -f, --full             print full patch level names
1994         --desc                 implies -s -c -D -k -C
1995         --local-merges         list merges from the same archive
1996         --foreign-merges       list merges from other archives
1997         --merges               list all merges
1998         --categories           show category names only
1999         --branches             show branch names only
2000         --versions             show version names only
2001         --omit-empty           omit empty or unchanged-since items
2002         --since SNAP-FILE      show revisions after those listed in SNAP-FILE
2003         --since-limits         limit output to items in the since file
2004         --snap SNAP-FILE       record the highest revisions shown
2005         --force                overwrite an existing snap-file
2006
2007
2008       Describe the contents of an archive in outline format.
2009
2010
2011       With LIMIT, look only that part of the archive.
2012
2013
2014       LIMIT may be a fully qualified name and may be an archive name.
2015
2016
2017   tla rbrowse
2018       print an outline describing an archive´s contents
2019
2020       Usage: tla rbrowse [options] [[ARCHIVE_NAME/]LIMIT_REGEX]
2021
2022         -h, --help               Display a help message and exit.
2023         -H                       Display a verbose help message and exit.
2024         -V, --version            Display a release identifier string
2025         --all                    Search all archives
2026         --since SNAP-FILE        Only show differences since SNAP-FILE
2027         --snap SNAP-FILE         Snap an archive
2028         -f, --snap-force         Force snap writing
2029         -r                       Reverse patch logs
2030         -s                       Print the summary of matching patches
2031         -c                       Print the creator of matching patches
2032         -D                       Print the date of matching patches
2033         --patch-regex REGEX      Only show revisions that contain [REGEX]
2034                                  (implies -s)
2035         -A, --archive            Use [archive] instead of default
2036         --show-sealed            Do not hide sealed branches
2037
2038
2039
2040       an outline of an archive  will  be  printed,  showing  the  categories,
2041       branches  and revisions of the specified archive if no archive is given
2042       then `my-default-archive` is used.
2043
2044
2045       If [LIMIT REGEX] is specified, revisions will only be shown if the cat‐
2046       egory,  branch  or  version  matches  [LIMIT  REGEX].  If --patch-regex
2047       [REGEX] is given, then only patchlogs matching [REGEX] will be given
2048
2049   tla categories
2050       list the categories in an archive
2051
2052       Usage: tla categories [options] [archive]
2053
2054         -h, --help     Display a help message and exit.
2055         -H             Display a verbose help message and exit.
2056         -V, --version  Display a release identifier string
2057                        and exit.
2058         -A, --archive  Override `my-default-archive´
2059
2060
2061       Print a list of the categories present in an archive.
2062
2063
2064   tla branches
2065       list the branches in an archive category
2066
2067       Usage: tla branches [options] [category]
2068
2069         -h, --help     Display a help message and exit.
2070         -H             Display a verbose help message and exit.
2071         -V, --version  Display a release identifier string
2072                        and exit.
2073         -A, --archive  Override `my-default-archive´
2074
2075
2076       Print a list of the branches within CATEGORY
2077
2078
2079   tla versions
2080       list the versions in an archive branch
2081
2082       Usage: tla versions [options] [branch]
2083
2084         -h, --help     Display a help message and exit.
2085         -H             Display a verbose help message and exit.
2086         -V, --version  Display a release identifier string
2087                        and exit.
2088         -A, --archive  Override `my-default-archive´
2089         -r, --reverse  sort from newest to oldest
2090
2091
2092       Print a list of versions within an archive branch.
2093
2094
2095       The list is ordinarily sorted from oldest to newest, but the order  can
2096       be changed with -r (--reverse).
2097
2098
2099   tla revisions
2100       list the revisions in an archive version
2101
2102       Usage: tla revisions [options] [version]
2103
2104         -h, --help     Display a help message and exit.
2105         -H             Display a verbose help message and exit.
2106         -V, --version  Display a release identifier string
2107                        and exit.
2108         -A, --archive  Override `my-default-archive´
2109         -r, --reverse  sort from newest to oldest
2110         -f, --full     list fully qualified names
2111         -s, --summary  print a summary of each patch
2112         -c, --creator  print the creator of each patch
2113         -D, --date     print the date of each patch
2114
2115
2116       Print a list of revisions within an archive version.
2117
2118
2119       The  list is ordinarily sorted from oldest to newest, but the order can
2120       be changed with -r (--reverse).
2121
2122
2123       With optional arguments specifying patches, list only those patches, if
2124       they exist.  If a listed patch does not exist, exit with status 1.  The
2125       -r (--reverse) flag has no effect with optional arguments.
2126
2127
2128   tla ancestry
2129       display the ancestory of a revision
2130
2131       Usage: tla ancestry [options] [revision]
2132
2133         -h, --help     Display a help message and exit.
2134         -H             Display a verbose help message and exit.
2135         -V, --version  Display a release identifier string
2136                        and exit.
2137         -A, --archive  Override `my-default-archive´
2138         -d, --dir DIR  cd to DIR first
2139         -m, --merges   show merges into this development line
2140         -r, --reverse  list oldest to newest
2141         -s, --summary  print a summary of each patch
2142         -c, --creator  print the creator of each patch
2143         -D, --date     print the date of each patch
2144
2145
2146       Print the ancestry of a revision.
2147
2148
2149   tla ancestry-graph
2150       display the ancestory of a revision
2151
2152       Usage: tla ancestry-graph [options] [revision]
2153
2154         -h, --help       Display a help message and exit.
2155         -H               Display a verbose help message and exit.
2156         -V, --version    Display a release identifier string
2157                          and exit.
2158         -A, --archive    Override `my-default-archive´
2159         -d, --dir DIR    cd to DIR first
2160         -m, --merges     show merges into this development line
2161         -r, --reverse    list oldest to newest
2162         -i, --immediate  show only the immediate ancestor
2163         -p, --previous   show the (namespace) previous revision
2164
2165
2166       Print a list describing the ancestry of a revision.
2167
2168
2169   tla cat-archive-log
2170       print the contents of an archived log entry
2171
2172       Usage: tla cat-archive-log [options] revision
2173
2174         -h, --help     Display a help message and exit.
2175         -H             Display a verbose help message and exit.
2176         -V, --version  Display a release identifier string
2177                        and exit.
2178         -A, --archive  Override `my-default-archive´
2179         --headers      show only log headers
2180
2181
2182       Retrieve and print the log message for the indicated revision from  its
2183       archive.
2184
2185
2186   tla cacherev
2187       cache a full source tree in an archive
2188
2189       Usage: tla cacherev [options] [revision]
2190
2191         -h, --help       Display a help message and exit.
2192         -H               Display a verbose help message and exit.
2193         -V, --version    Display a release identifier string
2194                          and exit.
2195         -A, --archive    Override `my-default-archive´
2196         --cache DIR      cache root for trees with pristines
2197
2198
2199       Cache a full-text copy of the indicated revision in the archive.   This
2200       can speed up subsequent calls to "tla  get"  for  that  and  subsequent
2201       revisions.
2202
2203
2204       If  no  revision  is  specified,  but  the command is run from within a
2205       project tree, cache the latest revision in the default version of  that
2206       tree.
2207
2208
2209   tla cachedrevs
2210       list cached revisions in an archive
2211
2212       Usage: tla cachedrevs [options] [version]
2213
2214         -h, --help     Display a help message and exit.
2215         -H             Display a verbose help message and exit.
2216         -V, --version  Display a release identifier string
2217                        and exit.
2218         -A, --archive  Override `my-default-archive´
2219
2220
2221       Report  which  revisions  of VERSION have been cached as whole trees in
2222       the archive.
2223
2224
2225       See also "tla cacherev -H".
2226
2227
2228   tla uncacherev
2229       remove a cached full source tree from an archive
2230
2231       Usage: tla uncacherev [options] revision [dir]
2232
2233         -h, --help     Display a help message and exit.
2234         -H             Display a verbose help message and exit.
2235         -V, --version  Display a release identifier string
2236                        and exit.
2237         -A, --archive  Override `my-default-archive´
2238
2239
2240       Remove the cached form of REVISION from its archive.
2241
2242
2243       If REVISION is not specified, but the command  is  run  from  within  a
2244       project  tree,  uncache  the  latest revision in the default version of
2245       that tree.
2246
2247
2248       Also see "tla cacherev -H".
2249
2250
2251   tla archive-meta-info
2252       report meta-info from an archive
2253
2254       Usage: tla archive-meta-info [options] item-name
2255
2256         -h, --help     Display a help message and exit.
2257         -H             Display a verbose help message and exit.
2258         -V, --version  Display a release identifier string
2259                        and exit.
2260         -A, --archive  Override `my-default-archive´
2261
2262
2263       Print the contents of a meta-info file from an archive. For example,
2264
2265           % tla archive-meta-info name
2266
2267
2268       prints the official name of your default archive.
2269
2270
2271   tla archive-snapshot
2272       update an archive snapshot
2273
2274       Usage: tla archive-snapshot [options] dir [limit]
2275
2276         -h, --help     Display a help message and exit.
2277         -H             Display a verbose help message and exit.
2278         -V, --version  Display a release identifier string
2279                        and exit.
2280         -A, --archive  Override `my-default-archive´
2281
2282
2283       Update the directory DIR with a "snapshot" of of  an  archive  (or  the
2284       part of the archive indicated by LIMIT
2285
2286
2287       For  each archive snapshotted, DIR will contain a file and subdirectory
2288       (where $ARCH is the name of the archive):
2289
2290           ./$ARCH.added
2291           ./$ARCH/
2292
2293
2294       Similarly, for each category snapshotted, DIR will contain:
2295
2296           ./$ARCH/$CAT.added
2297           ./$ARCH/$CAT/
2298
2299
2300       and so on, recursively, for branches and versions.
2301
2302
2303       For each revision, the snapshot contains:
2304
2305           ./$ARCH/$CAT/$BRANCH/$VERSION/$REVISION.added
2306
2307
2308       and that file contains a copy of the patch log entry for that revision.
2309
2310
2311       Snapshots can be used in combination with other tools (´make´  is  sug‐
2312       gested)  to  trigger one-time events in response to new additions to an
2313       archive.
2314
2315
2316   tla archive-version
2317       list the archive-version in an archive
2318
2319       Usage: tla archive-version [options]
2320
2321         -h, --help     Display a help message and exit.
2322         -H             Display a verbose help message and exit.
2323         -V, --version  Display a release identifier string
2324                        and exit.
2325         -A, --archive  Override `my-default-archive´
2326
2327
2328       Print the archive format identifier string of an arch archive.
2329
2330
2331   tla archive-fixup
2332       fix ancillary files in an archive
2333
2334       Usage: tla archive-fixup [options]
2335
2336         -h, --help     Display a help message and exit.
2337         -H             Display a verbose help message and exit.
2338         -V, --version  Display a release identifier string
2339                        and exit.
2340         -A, --archive  Override `my-default-archive´
2341
2342
2343       This is  a  kind  of  "catch-all"  command  to  fix  the  non-standard,
2344       non-transactional  state of an archive.  Currently its sole function is
2345       to repair .listing files in archives that use them.
2346
2347

PATCH LOG COMMANDS

2349   tla make-log
2350       initialize a new log file entry
2351
2352       Usage: tla make-log [options] [version]
2353
2354         -h, --help     Display a help message and exit.
2355         -H             Display a verbose help message and exit.
2356         -V, --version  Display a release identifier string
2357                        and exit.
2358         -A, --archive  Override `my-default-archive´
2359         -d, --dir DIR  cd to DIR first
2360
2361
2362       Create (if needed) a log entry file in the root  of  the  project  tree
2363       containing DIR, for the indicated VERSION.
2364
2365
2366       The name of the new log file is printed to standard output.
2367
2368
2369   tla log-versions
2370       list patch log versions in a project tree
2371
2372       Usage: tla log-versions [options]
2373
2374         -h, --help               Display a help message and exit.
2375         -H                       Display a verbose help message and exit.
2376         -V, --version            Display a release identifier string
2377                                  and exit.
2378         -d, --dir DIR            cd to DIR first
2379         -a, --archive ARCHIVE    list only logs for ARCHIVE
2380         -c, --category CATEGORY  list only logs for CATEGORY
2381         -b, --branch BRANCH      list only logs for BRANCH
2382         -v, --vsn VERSION        list only logs for VERSION
2383         -r, --reverse            reverse the sort order
2384
2385
2386       Print  the  list  of  versions  for  which  there are patch logs in the
2387       project tree containing DIR (or the current directory).
2388
2389
2390   tla add-log-version
2391       add a patch log version to a project tree
2392
2393       Usage: tla add-log-version [options] [archive]/version
2394
2395         -h, --help     Display a help message and exit.
2396         -H             Display a verbose help message and exit.
2397         -V, --version  Display a release identifier string
2398                        and exit.
2399         -A, --archive  Override `my-default-archive´
2400         -d, --dir DIR  cd to DIR first
2401
2402
2403       Add an initially empty list of patch log for  VERSION  to  the  project
2404       tree containing DIR (or the current directory).
2405
2406
2407       A  project tree patch log is a pre-requisite for checking the directory
2408       in on that version, or updating with patches from that version.
2409
2410
2411       Note that versions recorded for a project tree are  recorded  by  fully
2412       qualified  version  names:  an  archive name plus the name of a version
2413       within that archive.
2414
2415
2416   tla remove-log-version
2417       remove a version´s patch log from a project tree
2418
2419       Usage: tla remove-log-version [options] [archive]/version
2420
2421         -h, --help     Display a help message and exit.
2422         -H             Display a verbose help message and exit.
2423         -V, --version  Display a release identifier string
2424                        and exit.
2425         -A, --archive  Override `my-default-archive´
2426         -d, --dir DIR  cd to DIR first
2427
2428
2429       Remove the patch log for VERSION from the project tree  containing  DIR
2430       (or the current directory).
2431
2432
2433       Use  this  command  with caution -- it erases revision history from the
2434       project tree!
2435
2436
2437   tla logs
2438       list patch logs for a version in a project tree
2439
2440       Usage: tla logs [options] [[archive]/version ...]
2441
2442         -h, --help            Display a help message and exit.
2443         -H                    Display a verbose help message and exit.
2444         -V, --version         Display a release identifier string
2445                               and exit.
2446         -A, --archive         Override `my-default-archive´
2447         -d, --dir DIR         cd to DIR first
2448         -r, --reverse         sort from newest to oldest
2449         -s, --summary         print the summary of each patch
2450         -c, --creator         print the creator of each patch
2451         -D, --date            print the date of each patch
2452         --local-merges        list merges from the same archive
2453         --foreign-merges      list merges from other archives
2454         --merges              list all merges
2455         -f, --full            print full patch level names
2456
2457
2458       Print the list of patches applied to a project tree DIR (or the current
2459       directory) from VERSION.
2460
2461
2462   tla cat-log
2463       print the contents of a project tree log entry
2464
2465       Usage: tla cat-log [options] revision-spec
2466
2467         -h, --help     Display a help message and exit.
2468         -H             Display a verbose help message and exit.
2469         -V, --version  Display a release identifier string
2470                        and exit.
2471         -A, --archive  Override `my-default-archive´
2472         -d, --dir DIR  cd to DIR first
2473
2474
2475       Retrieve  and  print  the  patch  log for the indicated revision from a
2476       project tree.
2477
2478
2479   tla changelog
2480       generate a ChangeLog from a patch log
2481
2482       Usage: tla changelog [options] [[archive]/version]
2483
2484         -h, --help                  Display a help message and exit.
2485         -H                          Display a verbose help message and exit.
2486         -V, --version               Display a release identifier string
2487                                     and exit.
2488         -A, --archive               Override `my-default-archive´
2489         -d, --dir DIR               cd to DIR first
2490         --no-files                  exclude file lists from ChangeLog
2491         --untagged                  don´t implicitly tag the output file
2492         --new-entry PATCH,FILE      make FILE the first (top) entry
2493                                       for patch level PATCH
2494
2495
2496       Generate a ChangeLog for VERSION from the patch log for DIR.
2497
2498
2499   tla log-for-merge
2500       generate a log entry body for a merge
2501
2502       Usage: tla log-for-merge [options] [[archive]/version]
2503
2504         -h, --help     Display a help message and exit.
2505         -H             Display a verbose help message and exit.
2506         -V, --version  Display a release identifier string
2507                        and exit.
2508         -A, --archive  Override `my-default-archive´
2509         -d, --dir DIR  cd to DIR first
2510         -r, --reverse  sort from newest to oldest
2511
2512
2513       Generate a log entry body describing a merge into VERSION.
2514
2515
2516   tla merges
2517       report where two branches have been merged
2518
2519       Usage: tla merges [options] INTO [FROM]
2520
2521         -h, --help     Display a help message and exit.
2522         -H             Display a verbose help message and exit.
2523         -V, --version  Display a release identifier string
2524                        and exit.
2525         -A, --archive  Override `my-default-archive´
2526         -d, --dir DIR  cd to DIR first
2527         -r, --reverse  sort from newest to oldest
2528         -f, --full     print full patch level names
2529
2530
2531       Print a list of pairs of patch level names:
2532
2533               %s     %s   INTO-RVN  FROM-RVN
2534
2535
2536       where each pair indicates that at patch level  INTO-RVN  of  INTO,  the
2537       patch log entry FROM-RVN was added.
2538
2539
2540       FROM  may be a branch name, version name, or revision name. If a branch
2541       or version name, all merges from that branch or version  are  reported.
2542       If  a  revision  name, only the merge points for that specific revision
2543       are reported.
2544
2545
2546       INTO may be a version name or revision name.  If a  version  name,  all
2547       merge  points within that version are printed.  If a revision name, all
2548       merge points at that revision or earlier are printed.
2549
2550
2551       Output is sorted using patch-level ordering of the first column.
2552
2553
2554       Included patches are listed by full name  unless  FROM  is  a  revision
2555       name.   If  FROM  is  a  revision,  --full  causes  its full name to be
2556       printed.
2557
2558
2559   tla new-merges
2560       list tree patches new to a version
2561
2562       Usage: tla new-merges [options] [[archive]/version]
2563
2564         -h, --help     Display a help message and exit.
2565         -H             Display a verbose help message and exit.
2566         -V, --version  Display a release identifier string
2567                        and exit.
2568         -A, --archive  Override `my-default-archive´
2569         -d, --dir DIR  cd to DIR first
2570         -r, --reverse  sort from newest to oldest
2571
2572
2573       List all patch log entries in the tree containing  DIR  that  have  not
2574       already been merged with VERSION.
2575
2576

MULTI-PROJECT CONFIGURATION COMMANDS

2578   tla build-config
2579       instantiate a multi-project config
2580
2581       Usage: tla build-config [options] config
2582
2583         -h, --help          Display a help message and exit.
2584         -H                  Display a verbose help message and exit.
2585         -V, --version       Display a release identifier string
2586                             and exit.
2587         -d, --dir DIR       cd to DIR first
2588         --no-pristines      don´t create pristine copies
2589         --link               hardlink  files  to  revision library instead of
2590       copying
2591         --library           ensure revisions are in the revision library
2592         --sparse            add library entries sparsely (--link, --library)
2593         -r, --release-id    overwrite ./=RELEASE-ID for this config
2594
2595
2596       Build the named configuration.  See also "tla cat-config -H".
2597
2598
2599   tla cat-config
2600       output information about a multi-project config
2601
2602       Usage: tla cat-config [options] config
2603
2604         -h, --help        Display a help message and exit.
2605         -H                Display a verbose help message and exit.
2606         -V, --version     Display a release identifier string
2607                           and exit.
2608         -d, --dir DIR     cd to DIR first
2609         -o, --output CFG  write the output as config CFG
2610         -f, --force       overwrite an exiting config (with --output)
2611         -s, --snap        Show current patch levels of subtree packages.
2612         --unescaped       show filenames in unescaped form
2613
2614
2615       Parse and print the indicate config file from a project tree
2616
2617
2618       A config file contains blank lines, comment lines  starting  with  "#",
2619       and  config  specification  lines.    The  config  file called $NAME is
2620       stored in a project tree as ./configs/$NAME or as ./$NAME.
2621
2622
2623       A config specification line contains a relative path within  a  project
2624       tree,  and  a specification of the project or revision to store in that
2625       location.
2626
2627
2628       For example, the line:
2629
2630          ./src/arch   lord@emf.net--2003b/arch--devo--1.0
2631
2632
2633       means that, when building the configuration,  the  latest  revision  of
2634       arch--devo--1.0 should be created within the tree as ./src/arch.
2635
2636
2637       The  project  specification  can  be a branch name, version name or the
2638       name of a specific revision.
2639
2640
2641       The option --snap says to examine the project tree to  find  out  which
2642       revisions  of configured project are printed, and generate a new config
2643       specification that references those specific revisions.   For  example,
2644       the output for the line shown above might be:
2645
2646           ./src/arch  lord@emf.net--2003b/arch--devo--1.0--patch-21
2647
2648
2649       The  option --output causes the output from this command to be recorded
2650       as a new configuration file (or to replace an existing file if  --force
2651       is provided).
2652
2653

COMMANDS FOR BRANCHING AND MERGING

2655   tla tag
2656       create a continuation revision
2657
2658       Usage: tla tag [options] SOURCE-REVISION TAG-VERSION
2659
2660         -h, --help         Display a help message and exit.
2661         -H                 Display a verbose help message and exit.
2662         -V, --version      Display a release identifier string
2663                            and exit.
2664         -A, --archive      Override `my-default-archive´
2665         -l, --log FILE     commit with log file FILE
2666         --no-cacherev      Do not cacherev tag even if different archive
2667         --seal             create a version-0 revision
2668         --fix              create a versionfix revision
2669         -S,  --setup         Use  `archive-setup´  if  necessary;  implied by
2670       default.
2671         --no-setup         Do not use `archive-setup´ even if necessary.
2672
2673
2674       Create the continuation revision  TAG-VERSION  (branch  point  or  tag)
2675       which is equivalent to SOURCE-REVISION (plus a log entry).
2676
2677
2678       If no log entry is provided, a trivial log entry will be created.
2679
2680
2681   tla branch
2682       create a continuation revision
2683
2684       Usage: tla branch [options] [SOURCE] BRANCH
2685
2686         -h, --help         Display a help message and exit.
2687         -H                 Display a verbose help message and exit.
2688         -V, --version      Display a release identifier string
2689                            and exit.
2690         -A, --archive      Override `my-default-archive´
2691         -l, --log FILE     commit with log file FILE
2692         --no-cacherev      Do not cacherev tag even if different archive
2693         --seal             create a version-0 revision
2694         --fix              create a versionfix revision
2695
2696
2697       Create  the continuation revision BRANCH (branch point or tag) which is
2698       equivalent to SOURCE (plus a log entry). If no log entry is provided, a
2699       trivial log entry will be created.
2700
2701
2702       If  SOURCE is not specified, the current project tree revision is used,
2703       and the project tree is switched to BRANCH
2704
2705
2706   tla switch
2707       change the working trees version
2708
2709       Usage: tla switch [options] [package]
2710
2711         -h, --help     Display a help message and exit.
2712         -H             Display a verbose help message and exit.
2713         -V, --version  Display a release identifier string and exit.
2714         -A, --archive  Override `my-default-archive´.
2715         -d, --dir DIR  Change to DIR first.
2716         -q, --quiet    Suppress progress information
2717
2718
2719       change the working trees version to that of package, and  make  equiva‐
2720       lent to revision. Preserves uncommitted changes.
2721
2722
2723       Note:  tla  automatically switches to the _latest_ revision in the sup‐
2724       plied version if no revision explicitly specified.
2725
2726
2727   tla update
2728       update a project tree
2729
2730       Usage: tla update [options] [version/revision]
2731
2732         -h, --help       Display a help message and exit.
2733         -H               Display a verbose help message and exit.
2734         -V, --version    Display a release identifier string
2735                          and exit.
2736         -A, --archive    Override `my-default-archive´
2737         -d, --dir DIR    Update project tree in DIR (default `.´)
2738         -N, --forward    pass the --forward option to `patch´
2739         --dest DEST      Instead of modifying the project tree in-place,
2740                          make a copy of it to DEST and apply  the  result  to
2741       that
2742         --unescaped      show filenames in unescaped form
2743
2744
2745       Update a project tree by getting the latest revision of VERSION (or the
2746       default version of the project tree) and then applying a patch  set  of
2747       the  differences between the project tree and the highest revision with
2748       which it is up-to-date.
2749
2750
2751       If the merge involves conflicts, a warning message is printed, and  the
2752       new project tree will contain ".rej" files.
2753
2754
2755   tla replay
2756       apply revision changesets to a project tree
2757
2758       Usage: tla replay [options] [version/revision...]
2759
2760         -h, --help          Display a help message and exit.
2761         -H                  Display a verbose help message and exit.
2762         -V, --version       Display a release identifier string
2763                             and exit.
2764         -A, --archive       Override `my-default-archive´
2765         --list FILE         read a list of patches to apply
2766         --new               replay only new patches
2767         --reverse           reverse the named patch
2768         -N, --forward       pass the --forward option to `patch´
2769         -d, --dir DIR       Operate on project tree in DIR (default `.´)
2770         --dest DEST         Instead of modifying the project tree in-place,
2771                             make a copy of it to DEST and apply the result to
2772       that
2773         --skip-present      skip patches that contain 1 or  more  patch  logs
2774       already in this tree
2775         --unescaped         show filenames in unescaped form
2776
2777
2778       The result is formed by applying patches in the latest revision of VER‐
2779       SION (or the default version of the project tree), stopping  after  the
2780       first patch that causes conflicts.  If multiple VERSIONs are specified,
2781       they are applied in turn.
2782
2783
2784       If one or more specific REVISIONs (including patch-levels) is specified
2785       instead, only those patch sets, and no others, will be applied.
2786
2787
2788       With  the  --list  option, read a list of patches to apply from FILE (-
2789       for standard input).  Complete revision names should be listed, one per
2790       line.   replay  will  stop at the first patch in the list that causes a
2791       merge conflict, leaving behind files with names of the form:
2792
2793          ,,replay.conflicts-in --  the name of the  patch  that  caused  con‐
2794       flicts
2795
2796          ,,replay.remaining    --  the list of patches not yet applied
2797
2798
2799   tla star-merge
2800       merge mutually merged branches
2801
2802       Usage: tla star-merge [options] [FROM]
2803
2804         -h, --help               Display a help message and exit.
2805         -H                       Display a verbose help message and exit.
2806         -V, --version            Display a release identifier string
2807                                  and exit.
2808         -A, --archive            Override tree archive
2809         -c, --changes OUTPUT     Generate but don´t apply the changeset.
2810         -r, --reference VERSION  Set reference version (default: project tree
2811       version)
2812         -N, --forward            pass the --forward option to `patch´
2813         -t, --three-way          Perform a 3-way (diff3-style) merge.
2814         -d, --dir DIR            Operate on project tree in DIR (default `.´)
2815         --unescaped              show filenames in unescaped form
2816
2817
2818       Merge changes from FROM  into  the  project  tree,  considering  common
2819       ancestry  from  the  project  tree  reference version, REFERENCE (which
2820       defaults to the tree version of the  project  tree).  If  FROM  is  not
2821       given, it defaults to the tree revision.
2822
2823
2824       The  purpose  of  this  command is to merge changes between development
2825       lines which may have merged in both directions.   It uses merge history
2826       to  attempt  to  minimize  the  spurious  conflicts that can arise from
2827       `mutual merging´.
2828
2829
2830       FROM indicates a revision (it may be specified as a version name, indi‐
2831       cating the latest revision in that version).
2832
2833
2834       TREE is the project tree into which the merge will occur.
2835
2836
2837       Star-merge works by computing the most recent ANCESTOR revision of REF‐
2838       ERENCE and FROM and then applying the changeset:
2839
2840                delta (ANCESTOR, FROM)
2841
2842
2843       to TREE.
2844
2845
2846       The "most recent ancestor" is defined as follows:
2847
2848
2849       MAYBE_ANCESTOR_1 is defined as the highest patch level of FROM in  REF‐
2850       ERENCE  for  which both TREE and FROM have a patch log. In other words,
2851       it is the latest REFERENCE revision of FROM´s  version  already  merged
2852       into TREE.
2853
2854
2855       MAYBE_ANCESTOR_2 is defined as the highest patch level in REFERENCE for
2856       which both FROM and REFERENCE have a patch log.  In other words, it  is
2857       the latest revision of REFERENCE already merged into FROM.
2858
2859
2860       MAYBE_ANCESTOR_2,  if  it  is  not  "nil", was merged into FROM at some
2861       revision of FROM´s version, which we can call LAST_MERGE_INTO_FROM.
2862
2863
2864       If both MAYBE_ANCESTOR_1 or MAYBE_ANCESTOR_2 are nil, star-merge can do
2865       nothing.
2866
2867
2868       If  just  one  of MAYBE_ANCESTOR_1 is MAYBE_ANCESTOR_2 is not nil, then
2869       that non-nil value is ANCESTOR.
2870
2871
2872       If  both  MAYBE_ANCESTOR_1  and  MAYBE_ANCESTOR_2  are  not  nil,  then
2873       LAST_MERGE_INTO_FROM  and MAYBE_ANCESTOR_1 are compared (both are revi‐
2874       sions in FROM´s version). If MAYBE_ANCESTOR_1 is  the  later  revision,
2875       then  MAYBE_ANCESTOR_1  is  ANCESTOR,  otherwise,  MAYBE_ANCESTOR_2  is
2876       ANCESTOR.
2877
2878
2879   tla apply-delta
2880       compute a changeset between any two trees or revisions and apply it  to
2881       a project tree
2882
2883       Usage: tla apply-delta [options] FROM(REVISION|DIR) TO(REVISION|DIR)
2884
2885         -h, --help       Display a help message and exit.
2886         -H               Display a verbose help message and exit.
2887         -V, --version    Display a release identifier string
2888                          and exit.
2889         -A, --archive    Override `my-default-archive´
2890         -N, --forward    pass the --forward option to `patch´
2891         --cache DIR      specify a cache root for pristine copies
2892         -d, --dir DIR    Operate on project tree in DIR (default `.´)
2893         -t, --three-way  Perform a 3-way (diff3-style) merge.
2894         --dest DEST      Instead of modifying the project tree in-place,
2895                          make  a  copy  of it to DEST and apply the result to
2896       that
2897         --unescaped      show filenames in unescaped form
2898
2899
2900       A delta between A and B (both of which may be either a full revision or
2901       a project tree) is computed, and then applied to the project tree.
2902
2903
2904       Exit Status Codes:
2905
2906           0  No conflict during patch
2907           1  Conflicts occurred during patch
2908           3  Internal Error
2909
2910
2911   tla missing
2912       print patches missing from a project tree
2913
2914       Usage: tla missing [options] [version]
2915
2916         -h, --help          Display a help message and exit.
2917         -H                  Display a verbose help message and exit.
2918         -V, --version       Display a release identifier string
2919                             and exit.
2920         -A, --archive       Override `my-default-archive´
2921         -q, --quiet         produce no ordinary output
2922         -x, --exit-status   exit non-0 if patches are missing
2923         -d, --dir DIR       cd to DIR first
2924         -r, --reverse       sort from newest to oldest
2925         -s, --summary       display a summary of each missing patch
2926         -c, --creator       display the creator of each missing patch
2927         -D, --date          display the date of each missing patch
2928         -f, --full          print full revision names
2929         --merges            print a merge list for each missing patch
2930         --skip-present       skip  patches  that contain 1 or more patch logs
2931       already in this tree
2932
2933
2934       Print a list of patches missing in the project tree containing DIR  (or
2935       the  current  directory)  for  VERSION  (or the default version. of the
2936       project tree).
2937
2938
2939       The flag --merges means, for each patch, to print the list  of  patches
2940       included in the patch in two columns.  For example:
2941
2942               PATCH-A        PATCH-A
2943               PATCH-A        PATCH-B
2944               PATCH-A        PATCH-C
2945
2946
2947       means  that  PATCH-A  includes  the  changes  from PATCH-B and PATCH-C.
2948       (Every patch includes at least itself.)
2949
2950
2951       With -x, if there are missing patches, the command exits with status 1,
2952       otherwise with status 0.
2953
2954
2955       With -q, produce no output.
2956
2957
2958       WARNING:  At  this  time,  some error conditions *also* exit with error
2959       status 1, however, in situations where the caller is not concerned with
2960       errors, the exit status is still useful.
2961
2962
2963   tla join-branch
2964       add a version as an ancestor of a project tree
2965
2966       Usage: tla join-branch [options] version
2967
2968         -h, --help       Display a help message and exit.
2969         -H               Display a verbose help message and exit.
2970         -V, --version    Display a release identifier string
2971                          and exit.
2972         -A, --archive    Override `my-default-archive´
2973         -d, --dir DIR    Operate on project tree in DIR (default `.´)
2974         --dest DEST      Instead of modifying the project tree in-place,
2975                          make  a  copy  of it to DEST and apply the result to
2976       that
2977         --unescaped      show filenames in unescaped form
2978
2979
2980       VERSION--base-0 must be a continuation (e.g. tag). The command  replays
2981       the  changeset  for  VERSION--base-0 in the project tree, which has the
2982       effect of adding the log for the branch (making the tag an ancestor  of
2983       the resulting tree).
2984
2985
2986   tla sync-tree
2987       unify a project tree´s patch-log with a given revision
2988
2989       Usage: tla sync-tree [options] revision
2990
2991         -h, --help       Display a help message and exit.
2992         -H               Display a verbose help message and exit.
2993         -V, --version    Display a release identifier string
2994                          and exit.
2995         -A, --archive    Override `my-default-archive´
2996         -d, --dir DIR    Operate on project tree in DIR (default `.´)
2997         --dest DEST      Instead of modifying the project tree in-place,
2998                          make  a  copy  of it to DEST and apply the result to
2999       that
3000         --unescaped      show filenames in unescaped form
3001
3002
3003       The new project tree is formed by getting the REVISION and  adding  all
3004       patch-log  entries  from  REVISION.   No actual merging is performed --
3005       only the patch-log is changed.
3006
3007
3008   tla delta
3009       compute a changeset (or diff) between any two trees or revisions
3010
3011       Usage: tla delta [options] (REVISION|TREE)-A  (REVISION|TREE)-B  [DEST‐
3012       DIR]
3013
3014         -h, --help          Display a help message and exit.
3015         -H                  Display a verbose help message and exit.
3016         -V, --version       Display a release identifier string
3017                             and exit.
3018         -A, --archive       Override `my-default-archive´
3019         --cache DIR         specify a cache root for pristine copies
3020         -n, --no-changeset  do not generate a changeset
3021         --diffs             print changeset report with diffs (implies -n)
3022         --unescaped         show filenames in unescaped form
3023
3024
3025
3026       Given (REVISION|TREE)-A and (REVISION|TREE)-B, tla will build a change‐
3027       set that comprises the changes between REVISION-A and REVISION-B
3028
3029
3030       Example:
3031         tla delta tla--devo--1.1--patch-6             tla--devo--1.1--patch-8
3032       ,,changes
3033
3034         Will pull patch-6 and patch-8 from tla--devo--1.1 and compute
3035         a changeset, which will be saved in a newly created ,,changes
3036         directory. If you would like a report instead,
3037         append the --diffs option
3038

LOCAL CACHE COMMANDS

3040   tla changes
3041       report about local changes in a project tree
3042
3043       Usage: tla changes [options] [revision] [-- limit...]
3044
3045         -h, --help        Display a help message and exit.
3046         -H                Display a verbose help message and exit.
3047         -V, --version     Display a release identifier string and exit.
3048         -A, --archive     Override `my-default-archive´.
3049         -d, --dir DIR     Change to DIR first.
3050         -o, --output DIR  Save changeset in DIR (implies --keep).
3051         -v, --verbose     Verbose changeset report.
3052         -q, --quiet       Suppress progress information
3053         --diffs           Include diffs in the output.
3054         -k, --keep        Don´t remove the output directory on termination.
3055         --link            hardlink unchanged files to revision library
3056         --unescaped       show filenames in unescaped form
3057
3058
3059       Generate  a patch report describing the differences between the project
3060       tree containing DIR (or the current directory) and REVISION.
3061
3062
3063       The default patch level for a given version is  the  latest  level  for
3064       which the project tree has a patch.  The default archive and version is
3065       as printed by "tla tree-version".
3066
3067
3068   tla file-diff
3069       show local changes to a file
3070
3071       Usage: tla file-diff [options] file [revision]
3072
3073         -h, --help      Display a help message and exit.
3074         -H              Display a verbose help message and exit.
3075         -V, --version   Display a release identifier string
3076                         and exit.
3077         -A, --archive   Override `my-default-archive´
3078         -N, --new-file  Treat missing file as empty
3079
3080
3081       Print diffs between FILE and the corresponding file in a cached copy of
3082       REVISION.
3083
3084
3085       The  default  patch  level  for a given version is the latest level for
3086       which the project tree has a patch.  The default archive and version is
3087       as printed by "tla tree-version".
3088
3089
3090   tla file-find
3091       find given version of file
3092
3093       Usage: tla file-find [options] file [revision]
3094
3095         -h, --help       Display a help message and exit.
3096         -H               Display a verbose help message and exit.
3097         -V, --version    Display a release identifier string
3098                          and exit.
3099         -A, --archive    Override `my-default-archive´
3100         -N, --new-file   Print missing file as `/dev/null´
3101         --unescaped      show filenames in unescaped form
3102
3103
3104       Print  location of file corresponding to FILE in a cached copy of REVI‐
3105       SION
3106
3107
3108       The default patch level for a given version is  the  latest  level  for
3109       which the project tree has a patch.  The default archive and version is
3110       as printed by "tla tree-version".
3111
3112
3113   tla pristines
3114       list pristine trees in a project tree
3115
3116       Usage: tla pristines [options] [limit]
3117
3118         -h, --help      Display a help message and exit.
3119         -H              Display a verbose help message and exit.
3120         -V, --version   Display a release identifier string
3121                         and exit.
3122         -d, --dir DIR   cd to DIR first
3123         -u, --unlocked  return only unlocked pristines
3124         -l, --locked    return only locked pristines
3125         -r, --reverse   reverse sort order
3126
3127
3128       Print the list of pristine revisions cached in project tree DIR (or the
3129       current directory).
3130
3131
3132   tla lock-pristine
3133       lock (or unlock) a pristine tree
3134
3135       Usage: tla lock-pristine [options] revision
3136
3137         -h, --help     Display a help message and exit.
3138         -H             Display a verbose help message and exit.
3139         -V, --version  Display a release identifier string
3140                        and exit.
3141         -A, --archive  Override `my-default-archive´
3142         -d, --dir DIR  cd to DIR first
3143         -u, --unlock   unlock, rather than lock
3144
3145
3146       Lock the indicated pristine REVISION in the project tree containing DIR
3147       (or the current directory).  This  prevents  the  revision  from  being
3148       automatically recycled.
3149
3150
3151   tla add-pristine
3152       ensure that a project tree has a particular pristine revision
3153
3154       Usage: tla add-pristine [options] revision
3155
3156         -h, --help     Display a help message and exit.
3157         -H             Display a verbose help message and exit.
3158         -V, --version  Display a release identifier string
3159                        and exit.
3160         -A, --archive  Override `my-default-archive´
3161         -d, --dir DIR  cd to DIR first
3162
3163
3164       Extract  REVISION from an archive, creating a pristine copy. Store that
3165       pristine copy in the current directory´s project tree
3166
3167
3168   tla find-pristine
3169       find and print the path to a pristine revision
3170
3171       Usage: tla find-pristine [options] revision
3172
3173         -h, --help       Display a help message and exit.
3174         -H               Display a verbose help message and exit.
3175         -V, --version    Display a release identifier string
3176                          and exit.
3177         -A, --archive    Override `my-default-archive´
3178         -d, --dir DIR    cd to DIR first
3179         -u, --unlocked   return only an unlocked pristine
3180         -l, --locked     return only a locked pristine
3181         -t, --tree-only  search this tree only, not siblings
3182         -s, --silent     exit status only
3183
3184
3185       Print the location of a pristine copy of the indicated revision
3186
3187

REVISION LIBRARY COMMANDS

3189   tla my-revision-library
3190       print or change your revision library path
3191
3192       Usage: tla my-revision-library [options] [dir]
3193
3194         -h, --help         Display a help message and exit.
3195         -H                 Display a verbose help message and exit.
3196         -V, --version      Display a release identifier string
3197                            and exit.
3198         -e, --errname      specify program name for errors
3199         -d, --delete       unspecify your revision library
3200         -s, --silent       suppress reassuring messages
3201         --search           use the full search path
3202         --add              use the full add path
3203         --search-only      use the search-only path
3204         --add-only         use the add-only path
3205         --first            prepend to the path if setting (default appends)
3206
3207
3208       With no argument, and without -d,  print  the  path  to  your  revision
3209       library.
3210
3211
3212       With  an  argument,  record DIR as the path to your revision library in
3213       ~/.arch-params/=revision-library
3214
3215
3216       With the option -d (--delete) and no argument, ensure that you  do  not
3217       have a revision library path set in ~/.arch-params.
3218
3219
3220       If  no revision library is set, the program exits with status 1, print‐
3221       ing an error message unless the -s (--silent) option is given.
3222
3223
3224   tla library-dir
3225       (alias for my-revision-library)
3226
3227       Usage: tla library-dir [options] [dir]
3228
3229         -h, --help         Display a help message and exit.
3230         -H                 Display a verbose help message and exit.
3231         -V, --version      Display a release identifier string
3232                            and exit.
3233         -e, --errname      specify program name for errors
3234         -d, --delete       unspecify your revision library
3235         -s, --silent       suppress reassuring messages
3236         --search           use the full search path
3237         --add              use the full add path
3238         --search-only      use the search-only path
3239         --add-only         use the add-only path
3240         --first            prepend to the path if setting (default appends)
3241
3242
3243       With no argument, and without -d,  print  the  path  to  your  revision
3244       library.
3245
3246
3247       With  an  argument,  record DIR as the path to your revision library in
3248       ~/.arch-params/=revision-library
3249
3250
3251       With the option -d (--delete) and no argument, ensure that you  do  not
3252       have a revision library path set in ~/.arch-params.
3253
3254
3255       If  no revision library is set, the program exits with status 1, print‐
3256       ing an error message unless the -s (--silent) option is given.
3257
3258
3259   tla library-config
3260       configure parameters of a revision library
3261
3262       Usage: tla library-config [options] library-dir
3263
3264         -h, --help        Display a help message and exit.
3265         -H                Display a verbose help message and exit.
3266         -V, --version     Display a release identifier string
3267                           and exit.
3268         --greedy          make the library greedy
3269         --non-greedy      make the library not greedy
3270         --sparse          make the library sparse
3271         --non-sparse      make the library not sparse
3272
3273
3274       Set/show various parameters for a revision library.
3275
3276
3277   tla library-find
3278       find and print the location of a revision in the revision library
3279
3280       Usage: tla library-find [options] revision
3281
3282         -h, --help     Display a help message and exit.
3283         -H             Display a verbose help message and exit.
3284         -V, --version  Display a release identifier string
3285                        and exit.
3286         -A, --archive  Override `my-default-archive´
3287         -e, --errname  specify program name for errors
3288         -s, --silent   suppress reassuring messages
3289
3290
3291       Find REVISION in your revision library and print its path. If the revi‐
3292       sion  is not present, print an error message (unless --silent is speci‐
3293       fied) and exit with non-0 status.
3294
3295
3296   tla library-add
3297       add a revision to the revision library
3298
3299       Usage: tla library-add [options] revision
3300
3301         -h, --help            Display a help message and exit.
3302         -H                    Display a verbose help message and exit.
3303         -V, --version         Display a release identifier string
3304                               and exit.
3305         -A, --archive         Override `my-default-archive´
3306         -s, --sparse          Don´t fill in gaps in the library.
3307         --non-sparse          Fill in gaps in the library.
3308         -L, --library LIB     specify which library to add to
3309         --for-links PATH      require a lib on the same device as PATH
3310         --unescaped           show filenames in unescaped form
3311
3312
3313       Add REVISION to your revision library.
3314
3315
3316       This command has no effect and exits with status  0  if  the  indicated
3317       revision is already in the library.
3318
3319
3320   tla library-remove
3321       remove a revision from the revision library
3322
3323       Usage: tla library-remove [options] revision
3324
3325         -h, --help     Display a help message and exit.
3326         -H             Display a verbose help message and exit.
3327         -V, --version  Display a release identifier string
3328                        and exit.
3329         -A, --archive  Override `my-default-archive´
3330
3331
3332       Remove REVISION from your revision library.
3333
3334
3335       If  the  revision  is not present, print an error message and exit with
3336       non-0 status.
3337
3338
3339   tla library-archives
3340       list the archives in your revision library
3341
3342       Usage: tla library-archives [options]
3343
3344         -h, --help     Display a help message and exit.
3345         -H             Display a verbose help message and exit.
3346         -V, --version  Display a release identifier string
3347                        and exit.
3348
3349
3350       List all archives with records in the revision library.
3351
3352
3353   tla library-categories
3354       list the categories in your revision library
3355
3356       Usage: tla library-categories [options] [archive]
3357
3358         -h, --help     Display a help message and exit.
3359         -H             Display a verbose help message and exit.
3360         -V, --version  Display a release identifier string
3361                        and exit.
3362         -A, --archive  Override `my-default-archive´
3363
3364
3365       List all categories within a given archive in the revision library.
3366
3367
3368   tla library-branches
3369       list the branches in a library category
3370
3371       Usage: tla library-branches [options] [category]
3372
3373         -h, --help     Display a help message and exit.
3374         -H             Display a verbose help message and exit.
3375         -V, --version  Display a release identifier string
3376                        and exit.
3377         -A, --archive  Override `my-default-archive´
3378
3379
3380       List all branches within CATEGORY in the revision library.
3381
3382
3383   tla library-versions
3384       list the versions in a library branch
3385
3386       Usage: tla library-versions [options] [branch]
3387
3388         -h, --help     Display a help message and exit.
3389         -H             Display a verbose help message and exit.
3390         -V, --version  Display a release identifier string
3391                        and exit.
3392         -A, --archive  Override `my-default-archive´
3393         -r, --reverse  sort from newest to oldest
3394
3395
3396       List all versions within a particular archive/branch  with  records  in
3397       the revision library.
3398
3399
3400   tla library-revisions
3401       list the revisions in a library version
3402
3403       Usage: tla library-revisions [options] [version]
3404
3405         -h, --help     Display a help message and exit.
3406         -H             Display a verbose help message and exit.
3407         -V, --version  Display a release identifier string
3408                        and exit.
3409         -A, --archive  Override `my-default-archive´
3410         -r, --reverse  sort from newest to oldest
3411         -f, --full     list fully qualified names
3412         -s, --summary  print a summary of each patch
3413         -c, --creator  print the creator of each patch
3414         -D, --date     print the date of each patch
3415
3416
3417       List  all revisions within a particular archive/version with records in
3418       the revision library.
3419
3420
3421   tla library-log
3422       output a log message from the revision library
3423
3424       Usage: tla library-log [options] revision
3425
3426         -h, --help     Display a help message and exit.
3427         -H             Display a verbose help message and exit.
3428         -V, --version  Display a release identifier string
3429                        and exit.
3430         -A, --archive  Override `my-default-archive´
3431         -s, --silent   suppress reassuring messages
3432
3433
3434       Print the log message for REVISION from the library.
3435
3436
3437   tla library-file
3438       find a file in a revision library
3439
3440       Usage: tla library-file [options] file revision
3441
3442         -h, --help     Display a help message and exit.
3443         -H             Display a verbose help message and exit.
3444         -V, --version  Display a release identifier string
3445                        and exit.
3446         -A, --archive  Override `my-default-archive´
3447         --id           interpret FILE as an inventory id
3448         --this         interpret FILE as a file within a project tree
3449
3450
3451       Find FILE in REVISION in your revision library and print its  path.  If
3452       the  revision  or  file is not present, print an error message and exit
3453       with non-0 status.
3454
3455

PUBLISHED REVISIONS COMMANDS

3457   tla grab
3458       grab a published revision
3459
3460       Usage: tla grab [options] location
3461
3462         -h, --help     Display a help message and exit.
3463         -H             Display a verbose help message and exit.
3464         -V, --version  Display a release identifier string
3465                        and exit.
3466
3467
3468       Grabs a published revision from LOCATION.
3469
3470

MISCELLANEOUS SCRIPTING SUPPORT

3472   tla parse-package-name
3473       parse a package name
3474
3475       Usage: tla parse-package-name [options] name
3476
3477         -h, --help             Display a help message and exit.
3478         -H                     Display a verbose help message and exit.
3479         -V, --version          Display a release identifier string
3480                                and exit.
3481         -A, --archive          Override `my-default-archive´
3482         -a, --arch             print the archive name
3483         --non-arch             print the non-archive part of the name
3484         -c, --category         print the category name
3485         -b, --branch           print the branch name
3486         -p, --package          print the package name
3487         -v, --vsn              print the version id
3488         --package-version      print the category--branch--version
3489         -l, --lvl              print the patch level
3490         --patch-level          synonym for --lvl
3491
3492
3493       Options -b, -B, -p, -v, and -l cancel each other.
3494
3495
3496       For -b, -v, and -l, just the id string is printed without "--".
3497
3498
3499       For -p, the output is "<basename>--<branch>".
3500
3501
3502   tla valid-package-name
3503       test a package name for validity
3504
3505       Usage: tla valid-package-name [options] name
3506
3507         -h, --help         Display a help message and exit.
3508         -H                 Display a verbose help message and exit.
3509         -V, --version      Display a release identifier string
3510                            and exit.
3511         -e, --errname      specify program name for errors
3512         --archive          require and explicit archive
3513         --no-archive       prohibit and explicit archive
3514         -c, --category     require a category
3515         -p, --package      require category, permit branch
3516         -v, --vsn          require a version number
3517         -l, --patch-level  require a patch level
3518         --lvl              synonym for --patch-level
3519         -t, --tolerant     tolerate more specific names
3520
3521
3522       Exit with status 0 if PACKAGE is a valid package name, status 1  other‐
3523       wise.
3524
3525
3526       By default, require a basename or basename plus branch label.
3527
3528
3529       Options -v and -l cancel -b and vice versa.
3530
3531
3532       Option -l implies -v.
3533
3534
3535       If  an  error  name  is specified (-e or --errname), then invalid names
3536       cause an error message on stdout.  Otherwise, the exit  status  is  the
3537       only output.
3538
3539
3540       By  default,  validation is strict.  For example, -b checks for a valid
3541       basename and does not permit a branch label or version number.
3542
3543
3544       With -t, more specific names are permitted.  For example, -b will  per‐
3545       mit a branch name, version number, and patch level.
3546
3547
3548   tla escape
3549       print strings in escaped or unescaped form
3550
3551       Usage: tla escape [--unescaped] string
3552
3553         -h, --help       Display a help message and exit.
3554         -H               Display a verbose help message and exit.
3555         -V, --version    Display a release identifier string
3556                          and exit.
3557         --unescaped      show filenames in unescaped form
3558
3559
3560       Using Pika escaping rules.
3561
3562

ENVIRONMENT

3564       EDITOR If  $EDITOR is set, use its value as the path of the text editor
3565              arch is to run when asking the user for text  input.  If  unset,
3566              log  messages  must  be given on the command line using the `-L´
3567              parameter or in the file created by `tla make-log´.
3568
3569       HOME   User´s home directory, where arch  looks  for  .arch-cache/  and
3570              .arch-params/ .
3571
3572
3573       http_proxy HTTP_PROXY
3574              If $http_proxy or $HTTP_PROXY is set, arch used its value as the
3575              URL of the proxy to use for WebDAV  accesses.   $http_proxy  has
3576              higher priority than $HTTP_PROXY.  If unset, no proxy is used.
3577
3578       TMPDIR If  $TMPDIR  is  set,  arch creates temporary files in the given
3579              directory. Otherwise, it uses `/tmp´.
3580

FILES

3582       ${HOME}/.arch-cache/
3583              Directory where arch caches archive data
3584
3585       ${HOME}/.arch-params/
3586              Directory where all the user´s settings are stored.
3587
3588       ${HOME}/.arch-params/hook
3589              Hook script called after every execution of tla.
3590
3591       ${HOME}/.arch-params/signing/
3592              Directory where the commands for signing and checking signatures
3593              are stored.
3594

SEE ALSO

3596       http://gnuarch.org/, http://wiki.gnuarch.org/
3597
3598
3599
36001.3.5                             2009-06-29                            tla(1)
Impressum