R: Detect which files have changed

changedFiles {utils} | R Documentation

## Detect which files have changed

### Description

`fileSnapshot` takes a snapshot of a selection of files, recording summary information about each. `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, ...)

    ## S3 method for class 'fileSnapshot'
    print(x, verbose = FALSE, ...)

    ## S3 method for class 'changedFiles'
    print(x, verbose = FALSE, ...)

### Arguments

`path` | character vector; the path(s) to record.
`file.info` | logical; whether to record `file.info` values for each file.
`timestamp` | character string or `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.
`md5sum` | logical; whether MD5 summaries of each file should be taken as part of the snapshot.
`digest` | a function or `NULL`; a function with header `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.
`full.names` | logical; whether full names (as in `list.files`) should be recorded. Must be `TRUE` if `length(path) > 1`.
`...` | additional parameters to pass to `list.files` to control the set of files in the snapshots.
`before, after` | objects produced by `fileSnapshot`; two snapshots to compare. If `after` is missing, a new snapshot of the current file system will be produced for comparison, using arguments recorded in `before` as defaults.
`check.file.info` | character vector; which columns from `file.info` should be compared.
`x` | the object to print.
`verbose` | logical; whether to list all data when printing.

### Details

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

The `changedFiles` function compares two snapshots.

If the `timestamp` argument to `fileSnapshot` is length 1, a file with that name is created. If it is length 1 in `changedFiles`, the `file_test` function is used to compare the age of all files common to both `before` and `after` to it. This test may be unreliable: it compares the current modification time of the `after` files to the timestamp; that may not be the same as the modification time when the `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 `check.file.info` argument contains a non-empty character vector, the indicated columns from the result of a call to `file.info` will be compared.

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

### Value

`fileSnapshot` returns an object of class `"fileSnapshot"`. This is a list containing the fields

`info` | a data frame whose rownames are the filenames, and whose columns contain the requested snapshot data
`path` | the normalized `path` from the call
`timestamp, file.info, md5sum, digest, full.names` | a record of the other arguments from the call
`args` | other arguments passed via `...` to `list.files`.

`changedFiles` produces an object of class `"changedFiles"`. This is a list containing

`added, deleted, changed, unchanged` | character vectors of filenames from the before and after snapshots, with obvious meanings
`changes` | a logical matrix with a row for each common file, and a column for each comparison test. `TRUE` indicates a change in that test.

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

### Author(s)

Duncan Murdoch, using suggestions from Karl Millar and others.

### See Also

`file.info`, `file_test`, `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

[Package utils version 3.1.2 Index]