apenwarr-redo/Documentation/redo-stamp.md

# NAME

redo-stamp - detect if the current target has meaningfully changed

# SYNOPSIS

redo-stamp <$3


# DESCRIPTION

Normally, when `redo`(1) builds a target T, all the other
targets that depend on T are marked as out of date.  Even
if the rebuilt T is identical to the old one, all its
dependents need to be rebuilt.

By calling redo-stamp from your .do script, you can tell
`redo` that even though the current target is building, its
output may turn out to be unchanged.  If it hasn't, `redo`
may then be able to avoid building other targets that
depend on this target.

redo-stamp marks the current target as changed or unchanged
by comparing its stdin to the input that was provided last
time redo-stamp was called for this target.

The stamp data can be anything you want. Some possibilities
are:

- the actual target file contents:

        redo-stamp <$3
        
- a list of filenames:

        find -name '*.[ch]' | sort | redo-stamp

- the contents of a web page:

        curl http://example.org | redo-stamp

To ensure that your target gets checked every time, you
might want to use `redo-always`(1).


# DISCUSSION

While using redo-stamp is simple, the way it
works is harder to explain.  Deciding if a target is
up to date or not is the job of `redo-ifchange`(1). 
Normally, a target is considered out of date when any of its
dependencies (direct or indirect) have changed.  When that
happens, `redo-ifchange` runs the .do script for the
target, which regenerates the entire dependency list,
including rebuilding any dependencies as necessary.

Imagine that we have the following dependency chain:

    T -> X -> Y -> Z

T depends on X, which depends on Y, which depends
on Z.  Now imagine someone has changed Z.

If someone runs `redo-ifchange T`, then redo-ifchange
checks if X is up to date; to do that, it checks if Y
is up to date; and to do that, it checks whether Z is up to
date - which it isn't.  Thus, Y is not up to date, which
means X isn't, which means T isn't either, and so we need
to run T.do.  `redo-ifchange` won't directly `redo X` just
because X is dirty; it redoes T, and T.do might eventually
call `redo-ifchange X` if it needs to.

When using redo-stamp, the behaviour is different.  Let's
say Y has used redo-stamp.  In the above sequence, Y is
outdated because Z has changed.  However, we don't know yet
if Y's stamp has changed, so we don't yet know if we need
to redo X, and thus we don't know if we need to redo T.  We
can't just run `redo T`, because that could waste a lot of
time if it turns out T didn't need to be rebuilt after all.

What we do instead is note whether the *only* dependencies
of T that are out of date are 'stamped' targets.  If *any*
dependencies of T are normal, out-of-date redo targets,
then T needs to be rebuilt anyway; we don't have to do
anything special.

If the only dependency of T that has changed is Y (a
'stamped' target), then we need to `redo Y` automatically
in order to determine if T needs to be rebuilt.  This is
the only time that `redo` ever rebuilds a target that
hasn't been explicitly asked for as part of a running .do
script.


# REDO

Part of the `redo`(1) suite.
    
# CREDITS

The original concept for `redo` was created by D. J.
Bernstein and documented on his web site
(http://cr.yp.to/redo.html).  This independent implementation
was created by Avery Pennarun and you can find its source
code at http://github.com/apenwarr/redo.


# SEE ALSO

`redo`(1), `redo-ifcreate`(1), `redo-ifchange`(1), `redo-always`(1)