@need 3200

@node Advanced Revision Library Use
@chapter Advanced Revision Library Use

By default, when you @code{get} a revision from an archive, arch stores a
"pristine copy" of that revision under the @code{@{arch@}} directory.


Also by default, when @code{get} a revison, arch builds the revision by
searching for the @code{import} ancestor or the nearest archive-cached
ancestor -- then applying later patches to construct the revision you
want.


@code{get} and similar operations can be made both faster and more space
efficient by using revision libraries.   For example, if @code{get} finds
the revision you asked for in a library, it will copy it directly from
there (rather than building it by patching) and skip building a
pristine copy under @code{@{arch@}}.


That's all well and good -- but it can be awkward to have to remember
to @code{library-add} revisions to your library.   This section will show
how you can automate the process.

@need 3200

@section Greedy Revision Libraries

A @geindex greedy revision library
@dfn{greedy revision library} has the property that whenever arch looks
to see if the library contains a particular revision, if the library
_doesn't_ contain that revision, arch will add it automatically.


You can make a particular revision library directory greedy with the
command:

@example
@group
        % tla library-config --greedy DIR
@end group
@group
@end group
@end example



@need 3200

@section Sparse Revision Libraries

When arch automatically adds a revision to a greedy library, normally
it does it in the default manner of @code{library-add}: it adds previous
revisions in the same version as well.


If you were adding a revision to a library by-hand you could avoid
that behavior with the @code{--sparse} option to @code{library-add}.   To obtain
that behavior for automatically added revisions, use:

@example
@group
        % tla library-config --sparse DIR
@end group
@group
@end group
@end example

@noindent
which means that if a revision is automatically added to the library
located at DIR, it is added as if the @code{--sparse} option to
@code{library-add} were being used.




@need 3200

@section Hard Linked Project Trees

@strong{Warning:} To save yourself some confusion, do not use the following
feature unless you understand (a) what a hard-link is and (b) what it
means for an editor to "break hard links when writing a file".   If
you understand those terms, and know that the editor you use does in
fact break hard links, then feel free to use this feature.


You can very rapidly @code{get} a revision from a revision library not by
copying it, but instead by making hard-links to it:

@example
@group
        % tla get --link REVISION
@end group
@group
@end group
@end example

The @code{build-config} command has a similar option:

@example
@group
        % tla build-config --link REVISION
@end group
@group
@end group
@end example

This can save considerable disk space and greatly speed up the @code{get}
operation.


(There is, of course, a small chance that when you use a hard-linked
tree something will go wrong and modify the files in the revision
library.  Arch will notice that if it happens and give you an error
message advising you to delete and reconstruct the problematic
revision in the library.)




@need 3200

@section Putting it All Together

To sum up, a very handy and efficient set up involves:


@strong{1)} Create one or more revision library directories.


@strong{2)} Make at least some of those libraries greedy and possibly sparse.


@strong{3)} Use the @code{--link} option to @code{get} and @code{build-config}.


When you work this way, and arch needs to automatically add a revision
to a library for you, it will search for a library on the appropriate
device (for hard-links purposes).   Among those it will search first
for a library that already contains the same version as the revision
you want and, failing that, for a greedy library.







