Re: [Gnu-arch-users] fixing selected commit [commit, undo, --except]

[Denys Duchier]

Tom Lord <address@hidden> writes:

> It would be helpful to me if you would post in this thread a detailed
> description of the semantics of limits, in this context.

Of course (I have tried to document this in the code - if the
documentation is insufficient, then it should be fixed - naturally
comments are rarely sufficient to convey the big picture).

OK, I'll give it a try (I am bit tired - just met a conf deadline):

A limit is given in the form of a pathname.  A file or directory is
said to satisfy a limit constraint if the limit is a (reflexive) "path
prefix" of said file or directory (not just a string prefix).  The
intent is that a file or directory should be included in the changeset
if it satisfies some limit constraint, regardless of whether it is
located in ORIG or in MOD.  Unfortunately, this consideration is
complicated by the need to distinguish between regular files and files
that record metadata (e.g. .arch-ids/*): limits are about what data to
include into the changeset, it is up to arch to correspondingly
include the appropriate metadata - this is a design decision that I
made: limits are NEVER about metadata, only about data.

First, I'll outline how limits are normalized and then how they are
interpreted.

1. NORMALIZATION

Since a limit is given in the form of a pathname, it can be either
relative or absolute.

if it is relative, then the current directory is prepended.

Now it must be in the form of an absolute pathname, and this one
_must_ be under the current project tree root (else this is an error).
This tree root is subtracted and replaced by "." (conceptually).

Now we have limits which are root-independent and are intended to
apply equally to ORIG and to MOD.

2. SEMANTICS

The full inventory is computed as well as the tables recording the
changes between ORIG and MOD.  These tables concern those entries
which are only in ORIG, those which are only in MOD, those which are
in both, and those which involve a renaming from ORIG to MOD.

Limits are used to prune this data.

The basic idea is that we should only keep entries that match some
limit.  As I mentioned earlier, this is made more complicated by the
fact that if we include a file into the changeset then we need to
include its metadata file(s) as well.  Currently, this means its id
file (if any) under the corresponding .arch-ids directory.

Another consideration is that if we include a file in the changeset,
then obviously it needs its host directory.  Thus including a file,
means pulling its ancestor directories into the changeset as well
(just the directories, not their contents).

Whenever a file or directory is included into the changeset, then its
metadata must also be pulled in.  For a directory, this means
including .arch-ids/=id, for a FILE, .arch-ids/FILE.id.

3. EXCEPT

Supplying the --except option inverts the interpretation of limits.
Instead of including, they now exclude.


er... that's about all I can manage at this hour.  If, as is all too
likely, I have been imprecise or left important clues out, please let
me know and I'll try to improve on my explanations tomorrow
(er... today, I guess - but later, much later).

Cheers,

-- 
Dr. Denys Duchier
Équipe Calligramme
LORIA, Nancy, FRANCE