NAME

ditto — copy directory hierarchies, create and extract archives

SYNOPSIS

DESCRIPTION

In its first form, ditto copies one or more source files or directories to a destination directory. If the destination directory does not exist it will be created before the first source is copied. If the destination directory already exists then the source directories are merged with the previous contents of the destination.

In its second form, ditto copies a file to the supplied dst_file pathname.

The next two forms reflect ditto's ability to create and extract archives. These archives can be either CPIO format (preferred for unix content) or PKZip (for Windows compatibility). src_archive (and dst_archive) can be the single character '-', causing ditto to read (write) archive data from stdin (or to stdout, respectively).

ditto follows symbolic links provided as arguments but does not follow any links as it traverses the source or destination hierarchies. ditto overwrites existing files, symbolic links, and devices in the destination when these are copied from a source. The resulting files, links, and devices will have the same mode, access time, modification time, owner, and group as the source items from which they are copied. Pipes, sockets, and files with names beginning with .nfs or .afpDeleted will be ignored. ditto does not modify the mode, owner, group, extended attributes, or ACLs of existing directories in the destination. Files and symbolic links cannot overwrite directories or vice-versa.

ditto can be used to "thin" Universal Mach-O binaries during a copy. ditto can also copy files selectively based on the contents of a BOM ("Bill of Materials") file. ditto preserves file hard links (but not directory hard links) present in the source directories and preserves setuid and setgid modes when run as the superuser.

ditto will preserve resource forks and HFS meta-data information when copying unless instructed otherwise using --norsrc . --norsrc will disable copy of resource forks, extended attributes, Access Control Lists (ACLs), as well as quarantine bits. DITTONORSRC can be set in the environment as an alias to --norsrc --noextattr --noacl --noqtn on the command line. However, each option can be individually turned on or off, see the OPTIONS section for more details.

OPTIONS

-h, --help

Print full usage.

-v

Print a line of output to stderr for each source directory copied.

-V

Print a line of output to stderr for every file, symbolic link, and device copied.

-X

When copying one or more source directories, do not descend into directories that have a different device ID.

-c

Create an archive at the destination path. The default format is CPIO, unless -k is given. CPIO archives should be stored in files with names ending in .cpio. Compressed CPIO archives should be stored in files with names ending in .cpgz.

-z

Create compressed CPIO archives, using gzip(1) compression.

-j

Create compressed CPIO archives, using bzip2(1) compression.

-x

Extract the archives given as source arguments. The format is assumed to be CPIO, unless -k is given. Compressed CPIO is automatically handled.

-k

Create or extract from a PKZip archive instead of the default CPIO. PKZip archives should be stored in filenames ending in .zip.

--keepParent

When creating an archive, embed the parent directory name src in dst_archive.

--arch arch

Thin Universal binaries to the specified architecture. If multiple --arch options are specified then the resulting destination file will contain each of the specified architectures (if they are present in the source file). arch should be specified as "arm64", "x86_64", etc.

--bom bom

Copy only files, links, devices, and directories that are present in the specified BOM.

--rsrc

Preserve resource forks and HFS meta-data. ditto will store this data in Carbon-compatible ._ AppleDouble files on filesystems that do not natively support resource forks. As of Mac OS X 10.4, --rsrc is default behavior.

--norsrc

Do not preserve resource forks and HFS meta-data. If both --norsrc and --rsrc are passed, whichever is passed last will take precedence. Both options override DITTONORSRC. Unless explicitly specified, --norsrc also implies --noextattr and --noacl to match the behavior of Mac OS X 10.4.

--extattr

Preserve extended attributes (requires --rsrc). As of Mac OS X 10.5, --extattr is the default.

--noextattr

Do not preserve extended attributes (requires --norsrc).

--qtn

Preserve quarantine information. As of Mac OS X 10.5, --qtn is the default.

--noqtn

Do not preserve quarantine information.

--acl

Preserve Access Control Lists (ACLs). As of Mac OS X 10.5, --acl is the default.

--noacl

Do not preserve ACLs.

--nocache

Do not perform copies using the Mac OS X Unified Buffer Cache. Files read and written will not be cached, although if the file is already present in the cache, the cached information will be used.

--hfsCompression

When copying files or extracting content from an archive, if the destination is an HFS+ or APFS volume that supports filesystem compression, all the content will be compressed if appropriate. This is only supported on Mac OS X 10.6 or later, and is only intended to be used in installation and backup scenarios that involve system files. Since files using filesystem compression are not readable on versions of Mac OS X earlier than 10.6, this flag should not be used when dealing with non-system files or other user-generated content that will be used on a version of Mac OS X earlier than 10.6.

--nohfsCompression

Do not compress files with filesystem compression when copying or extracting content from an archive unless the content is already compressed with filesystem compression. This flag is only supported on Mac OS X 10.6 or later. --nohfsCompression is the default.

--preserveHFSCompression

When copying files to an HFS+ or APFS volume that supports filesystem compression, ditto will preserve the compression of any source files that were using filesystem compression. This flag is only supported on Mac OS X 10.6 or later. --preserveHFSCompression is the default.

--nopreserveHFSCompression

Do not preserve filesystem compression when copying files that are already compressed with filesystem compression. This is only supported on Mac OS X 10.6 or later.

--sequesterRsrc

When creating a PKZip archive, preserve resource forks and HFS meta-data in the subdirectory __MACOSX. PKZip extraction will automatically find these resources.

--zlibCompressionLevel num

Sets the compression level to use when creating a PKZip archive. The compression level can be set from 0 to 9, where 0 represents no compression, and 9 represents optimal (slowest) compression. By default, ditto will use the default compression level as defined by zlib.

--password

When extracting a password-encrypted ZIP archive, you must specify --password to allow ditto to prompt for a password to use to extract the contents of the file. If this option is not provided, and a password-encrypted file is encountered, ditto will emit an error message.

--persistRootless

If a file being replaced has the SF_RESTRICTED flag or the com.apple.rootless extended attribute set, retain it even if the source file may not have had the same flag or attribute.

--nopersistRootless

Do not persist the SF_RESTRICTED flag or the com.apple.rootless extended attribute for files being replaced.

--nonAtomicCopies

Do not perform atomic copies when replacing existing files. By default ditto will atomically swap new files into place when completing a copy.

--segmentLargeFiles

When copying files to a CPIO archive, segment files larger than 8 gigabytes into multiple entries.

--keepBinaries

When copying files ditto will set aside the original Mach-O binary when it is being replaced. The file name will be changed to a random number preceeded by the prefix .BC.T_

--keepBinariesList path

When ditto keeps binary files it will record the location of the kept file in the file at the specified path.

--keepBinariesPattern regex

Keep any regular file that matches the specified regular expression. Note that this file must not be a Mach-O binary.

--lang lang

When copying files with an index bom specified via -b option the user can specify language variants to filter from the index bom. By default ditto will create a new index bom at /tmp/ditto.XXXXX representing the filtered contents. The user can direct the output bom via the -o flag.

--outBom bom

Specify an explicit path for the output bom. This bom will only be created if the user specified the -o flag or the -l flags.

--clone

Attempt to clone regular files when copying.

--noclone

Do not attempt to clone files.

--option key=value

Specify an arbitrary key value pair to be passed to the copier. The value can be a string, boolean, or integer. Booleans can be specified as 'true', 'false', 'yes', or 'no'.

EXAMPLES

The command:

The command:

The command:

The command:

The command:

The command:

The command:

The command:

The command:

ERRORS

ditto returns 0 if everything is copied, otherwise non-zero. ditto almost never gives up, preferring to report errors along the way. Diagnostic messages will be printed to standard error.

ENVIRONMENT

DITTOABORT

If the environment variable DITTOABORT is set, ditto will call abort(3) if it encounters a fatal error.

DITTONORSRC

If DITTONORSRC is set but --rsrc, --extattr, and --acl are not specified, ditto will not preserve those additional types of metadata.

DITTOKEEPBINARIESPATTERN

If the environment variable DITTOKEEPBINARIESPATTERN is set, ditto will keep files that match the regular expression. This matches the behavior of --keepBinariesPattern

DITTOKEEPBINARIESDIR

By default, ditto will keep the original file adjacent to its replacement. If the environment variable DITTOKEEPBINARIESDIR is set, ditto will move kept files into the specified directory path. The files will be renamed to a random UUID and the directory will be kept balanced.

DITTO_TEST_OPTIONS

If DITTO_TEST_OPTIONS is set to 1 ditto will print the parameters to be passed to BOMCopierCopyWithOptions for each source and destination pair, including the contents of the options dictionary. It will then exit without performing any copy operation.

BUGS

ditto doesn't copy directories into directories in the same way as cp(1). In particular,

SEE ALSO

bom(5), lsbom(8), mkbom(8), cpio(1), zip(1), gzip(1), bzip2(1), tar(1).

HISTORY

ditto first appeared in Mac OS X (10.0)