% File src/library/utils/man/changedFiles.Rd
% Part of the R package, https://www.R-project.org
% Copyright 2013 R Core Team
% Distributed under GPL 2 or later

\name{changedFiles}
\alias{fileSnapshot}
\alias{changedFiles}
\alias{print.changedFiles}
\alias{print.fileSnapshot}
\title{Detect which Files Have Changed}
\description{
\code{fileSnapshot} takes a snapshot of a selection of files,
recording summary information about each.  \code{changedFiles}
compares two snapshots, or compares one snapshot to the current state
of the file system.  The snapshots need not be the same directory;
this could be used to compare two directories.
}
\usage{
fileSnapshot(path = ".", file.info = TRUE, timestamp = NULL, 
	    md5sum = FALSE, digest = NULL, full.names = length(path) > 1,
	    ...) 

changedFiles(before, after, path = before$path, timestamp = before$timestamp, 
	    check.file.info = c("size", "isdir", "mode", "mtime"), 
	    md5sum = before$md5sum, digest = before$digest, 
	    full.names = before$full.names, ...)
	    
\S3method{print}{fileSnapshot}(x, verbose = FALSE, ...)

\S3method{print}{changedFiles}(x, verbose = FALSE, ...) 
} 

\arguments{ 

\item{path}{character vector; the path(s) to record. }
\item{file.info}{logical; whether to record \code{\link{file.info}}
values for each file.
}  

\item{timestamp}{character string or \code{NULL}; the name of a file
to write at the time the snapshot is taken.  This gives a quick test
for modification, but may be unreliable; see the Details. }

\item{md5sum}{logical; whether MD5 summaries of each file should be
taken as part of the snapshot. }

\item{digest}{a function or \code{NULL}; a function with header
\code{function(filename)} which will take a vector of filenames and
produce a vector of values of the same length, or a matrix with that
number of rows. }

\item{full.names}{logical; whether full names (as in
\code{\link{list.files}}) should be recorded. Must be \code{TRUE} if
\code{length(path) > 1}. }

\item{\dots}{ additional parameters to pass to
\code{\link{list.files}} to control the set of files in the snapshots.
}

\item{before, after}{objects produced by \code{fileSnapshot}; two
snapshots to compare.  If \code{after} is missing, a new snapshot of
the current file system will be produced for comparison, using
arguments recorded in \code{before} as defaults. }

\item{check.file.info}{character vector; which columns from
\code{\link{file.info}} should be compared. }

\item{x}{the object to print. }

\item{verbose}{logical; whether to list all data when printing. }

}
\details{

The \code{fileSnapshot} function uses \code{\link{list.files}} to
obtain a list of files, and depending on the \code{file.info},
\code{md5sum}, and \code{digest} arguments, records information about
each file.

The \code{changedFiles} function compares two snapshots. 

If the \code{timestamp} argument to \code{fileSnapshot} is length 1, a
file with that name is created. If it is length 1 in
\code{changedFiles}, the \code{\link{file_test}} function is used to
compare the age of all files common to both \code{before} and
\code{after} to it.  This test may be unreliable:  it compares the
current modification time of the \code{after} files to the timestamp;
that may not be the same as the modification time when the
\code{after} snapshot was taken.  It may also give incorrect results
if the clock on the file system holding the timestamp differs from the
one holding the snapshot files.

If the \code{check.file.info} argument contains a non-empty character
vector, the indicated columns from the result of a call to
\code{\link{file.info}} will be compared.

If \code{md5sum} is \code{TRUE}, \code{fileSnapshot} will call the
\code{tools::\link{md5sum}} function to record the 32 byte MD5
checksum for each file, and \code{changedFiles} will compare the
values.  The \code{digest} argument allows users to provide their own
digest function.

}

\value{

\code{fileSnapshot} returns an object of class \code{"fileSnapshot"}.
This is a list containing the fields 

\item{info}{a data frame whose rownames are the filenames, and whose
columns contain the requested snapshot data} 

\item{path}{the normalized \code{path} from the call} 

\item{timestamp, file.info, md5sum, digest, full.names}{a record of
the other arguments from the call} 

\item{args}{other arguments passed via \code{...} to
\code{\link{list.files}}.}

\code{changedFiles} produces an object of class \code{"changedFiles"}.
This is a list containing

\item{added, deleted, changed, unchanged}{character vectors of
filenames from the before and after snapshots, with obvious meanings}

\item{changes}{a logical matrix with a row for each common file, and a
column for each comparison test. \code{TRUE} indicates a change in
that test.}

\code{\link{print}} methods are defined for each of these types.  The
\code{\link{print}} method for \code{"fileSnapshot"} objects
displays the arguments used to produce them, while the one for
\code{"changedFiles"} displays the \code{added}, \code{deleted} and
\code{changed} fields if non-empty, and a submatrix of the
\code{changes} matrix containing all of the \code{TRUE} values.

}

\author{
Duncan Murdoch, using suggestions from Karl Millar and others.
}

\seealso{
\code{\link{file.info}}, \code{\link{file_test}}, \code{\link{md5sum}}.
}

\examples{
# Create some files in a temporary directory
dir <- tempfile()
dir.create(dir)
writeBin(1L, file.path(dir, "file1"))
writeBin(2L, file.path(dir, "file2"))
dir.create(file.path(dir, "dir"))

# Take a snapshot
snapshot <- fileSnapshot(dir, timestamp = tempfile("timestamp"), md5sum=TRUE)

# Change one of the files.
writeBin(3L:4L, file.path(dir, "file2"))

# Display the detected changes.  We may or may not see mtime change...
changedFiles(snapshot)
changedFiles(snapshot)$changes
}
\keyword{utilities}
\keyword{file}