From 897c218f8542164baa5515b4017d3db78e06640b Mon Sep 17 00:00:00 2001 From: Avery Pennarun Date: Sun, 16 Jan 2011 16:33:22 -0800 Subject: [PATCH] redo.md: explain .do file search-parent-dirs feature. --- Documentation/redo.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/Documentation/redo.md b/Documentation/redo.md index e5e5451..2cbf201 100644 --- a/Documentation/redo.md +++ b/Documentation/redo.md @@ -121,12 +121,23 @@ the following order: - default.do In all cases, the .do file must be in the same directory as -the target file. +the target file, or in one of the target's parent +directories. For example, if given a target named +`../a/b/xtarget.y`, redo will look for a .do file in the +following order: + +- $PWD/../a/b/xtarget.y +- $PWD/../a/b/default.y.do +- $PWD/../a/b/default.do +- $PWD/../a/default.y.do +- $PWD/../a/default.do +- $PWD/../default.y.do +- $PWD/../default.do The first matching .do file is executed as a `/bin/sh` script. The .do script is always executed with the current working directory set to the directory containing the .do -file (and thus the target). Because of that rule, the +file. Because of that rule, the following two commands always have exactly identical behaviour: @@ -153,6 +164,12 @@ The three arguments passed to the .do script are: Instead of using $3, the .do script may also write the produced data to stdout. +If the .do file is in the same directory as the target, $1 +and $3 are guaranteed to be simple filenames (with no path +component). If the .do file is in a parent directory of +the target, $1 and $3 will be relative paths (ie. will +contain slashes). + redo is designed to update its targets atomically, and only if the do script succeeds (ie. returns a zero exit code). Thus, you should never write directly to the target file,