From 62126fae6807e320085aab5a2c5eb7eb5bee3974 Mon Sep 17 00:00:00 2001 From: James Youngman Date: Fri, 20 Jun 2008 10:20:04 +0100 Subject: [PATCH] Add 'Find shallowest instance' worked example. To: address@hidden 2008-06-20 Randall Burton * doc/find.texi (Finding the Shallowest Instance): Add worked example explaining how to efficiently locate the shallowest instances of '.svn' or 'CVS' in a forest of project trees. * find/find.1 (EXAMPLES): Add the same example here (with slightly briefer wording). Signed-off-by: James Youngman --- doc/find.texi | 46 ++++++++++++++++++++++++++++++++++++++++++++++ find/find.1 | 25 +++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 0 deletions(-) diff --git a/doc/find.texi b/doc/find.texi index a8041d4..56d3e32 100644 --- a/doc/find.texi +++ b/doc/find.texi @@ -4062,6 +4062,7 @@ performed, and compares the different ways of achieving them. * Deleting Files:: * Copying A Subset of Files:: * Updating A Timestamp File:: +* Finding the Shallowest Instance:: @end menu @node Deleting Files @@ -4609,6 +4610,51 @@ other, to the nearest second. The second @code{find} command takes each resulting file one at a time, and if that is newer than the timestamp file, the timestamp is updated. address@hidden Finding the Shallowest Instance address@hidden Finding the Shallowest Instance + +Suppose you maintain local copies of sources from various projects, +each with their own choice of directory organisation and source code +management (SCM) tool. You need to periodically synchronize each +project with its upstream tree. As the number local repositories +grows, so does the work involved in maintaining synchronization. SCM +utilities typically create some sort of administrative directory: .svn +for Subversion, CVS for CVS, and so on. These directories can be used +as a key to search for the bases of the project source trees. Suppose +we have the following directory structure: + address@hidden +repo/project1/CVS +repo/gnu/project2/.svn +repo/gnu/project3/.svn +repo/gnu/project3/src/.svn +repo/gnu/project3/doc/.svn +repo/project4/.git address@hidden smallexample + +One would expect to update each of the @file{projectX} directories, +but not their subdirectories (src, doc, etc.). To locate the project +roots, we would need to find the least deeply nested directories +containing an SCM-related subdirectory. The following command +discovers those roots efficiently. It is efficient because it avoids +searching subdirectories inside projects whose SCM directory we +already found. + address@hidden +find repo/ -exec test -d @address@hidden/.svn -o -d @address@hidden/.git -o -d @address@hidden/CVS \; -print -prune address@hidden smallexample + +In this example, @command{test} is used to tell if we are currently +examining a directory which appears to the a project's root directory +(because it has an SCM subdirectory). When we find a project root, +there is no need to search inside it, and @code{-prune} makes sure +that we descend no further. + +For large, complex trees like the Linux kernel, this will prevent +searching a large portion of the structure, saving a good deal of +time. + + @node Security Considerations @chapter Security Considerations diff --git a/find/find.1 b/find/find.1 index 460916b..dd3b028 100644 --- a/find/find.1 +++ b/find/find.1 @@ -1944,6 +1944,31 @@ binds more tightly than this is the default anyway, but the parentheses help to show what is going on. +.P +.nf +.B find repo/ -exec test -d {}/.svn -o -d {}/.git -o -d {}/CVS \; \e +.B -print -prune +.fi + +Given the following directory of projects and their associated SCM +administrative directories, perform an efficient search for the +projects' roots: + +.nf +.B repo/project1/CVS +.B repo/gnu/project2/.svn +.B repo/gnu/project3/.svn +.B repo/gnu/project3/src/.svn +.B repo/project4/.git + +.fi +In this example, +.B \-prune +prevents unnecessary descent into directories that have already been +discovered (for example we do not search project3/src because we +already found project3/.svn), but ensures sibling directories +(project2 and project3) are found. + .SH EXIT STATUS .PP .B find -- 1.5.5.3