.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TREESCAN 1p"
.TH TREESCAN 1p 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
treescan \- scan directory trees, list dirs/files, stat, sync, grep
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&   treescan [OPTION...] [PATH...]
\&
\&      \-q, \-\-quiet    do not print list of files/directories
\&      \-0, \-\-print0   use null character instead of newline to separate names
\&      \-s, \-\-stat     call stat on every entry, to get stat data into cache
\&      \-d, \-\-dirs     only list dirs
\&      \-f, \-\-files    only list files
\&      \-p, \-\-progress regularly print progress to stderr
\&          \-\-sync     open/fsync/close every entry
\&      \-g, \-\-grep=RE  only list files that match the given perl RegEx
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fItreescan\fR command scans directories and their contents
recursively. By default it lists all files and directories (with trailing
\&\f(CW\*(C`/\*(C'\fR), but it can optionally do various other things.
.PP
If no paths are given, \fItreescan\fR will use \f(CW\*(C`.\*(C'\fR, the current directory.
.SS OPTIONS
.IX Subsection "OPTIONS"
.IP "\-q, \-\-quiet" 4
.IX Item "-q, --quiet"
By default, \fItreescan\fR prints the full paths of all directories or files
it finds. This option disables printing of filenames completely. This is
useful if you want to run \fItreescan\fR solely for its side effects, such as
pulling \f(CW\*(C`stat\*(C'\fR data into memory.
.IP "\-0, \-\-print0" 4
.IX Item "-0, --print0"
Instead of using newlines, use null characters after each filename. This
is useful to avoid quoting problems when piping the result into other
programs (for example, GNU \fIgrep\fR, \fIxargs\fR and so on all have options to
deal with this).
.IP "\-s, \-\-stat" 4
.IX Item "-s, --stat"
Normally, \fItreescan\fR will use heuristics to avoid most \f(CW\*(C`stat\*(C'\fR calls,
which is what makes it so fast. This option forces it to \f(CW\*(C`stat\*(C'\fR every file.
.Sp
This is only useful for the side effect of pulling the \f(CW\*(C`stat\*(C'\fR data into
the cache. If your disk cache is big enough, it will be filled with
file meta data after \fItreescan\fR is done, which can speed up subsequent
commands considerably. Often, you can run \fItreescan\fR in parallel with
other directory-scanning programs to speed them up.
.IP "\-d, \-\-dirs" 4
.IX Item "-d, --dirs"
Only lists directories, not file paths. This is useful if you quickly want
a list of directories and their subdirectories.
.IP "\-f, \-\-files" 4
.IX Item "-f, --files"
Only list files, not directories. This is useful if you want to operate on
all files in a hierarchy, and the directories would ony get in the way.
.IP "\-p, \-\-progress" 4
.IX Item "-p, --progress"
Regularly print some progress information to standard error. This is
useful to get some progress information on long running tasks. Since
the progress is printed to standard error, you can pipe the output of
\&\fItreescan\fR into other programs as usual.
.IP \-\-sync 4
.IX Item "--sync"
The \f(CW\*(C`\-\-sync\*(C'\fR option can be used to make sure all the files/dirs in a tree
are sync'ed to disk. For example this could be useful after unpacking an
archive, to make sure the files hit the disk before deleting the archive
file itself.
.IP "\-g, \-\-grep=RE" 4
.IX Item "-g, --grep=RE"
This applies a perl regular expression (see the perlre manpage) to all paths that would normally be printed
and will only print matching paths.
.Sp
The regular expression uses an \f(CW\*(C`/s\*(C'\fR (single line) modifier by default, so
newlines are matched by \f(CW\*(C`.\*(C'\fR.
.SH AUTHOR
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://home.schmorp.de/
.Ve