DITTO(1) General Commands Manual DITTO(1)

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 preceded 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:

ditto src_directory dst_directory

copies the contents of src_directory into dst_directory, creating dst_directory if it does not already exist.

The command:

ditto src_directory dir/dst_directory

copies the contents of src_directory into dir/dst_directory, creating dir and dst_directory if they don’t already exist.

The command:

ditto src-1 … src-n dst_directory

copies the contents of all of the src directories into dst_directory, creating dst_directory if it does not already exist.

The command:

ditto --arch ppc universal_file thin_file

copies the contents of universal_file into thin_file, thinning executable code to ppc-only on the fly.

The command:

ditto -c --norsrc Scripts -|ssh rhost ditto -x --norsrc - ./Scripts

copies Scripts, skipping any resources or meta-data, to rhost.

The command:

pax -f archive.cpio

will list the files in the CPIO archive archive.cpio.

The command:

pax -zf archive.cpgz

will list the files in the compressed CPIO archive archive.cpgz.

The command:

ditto -c -k --sequesterRsrc --keepParent src_directory archive.zip

will create a PKZip archive similarly to the Finder’s Compress functionality.

The command:

unzip -l archive.zip

will list the files in the PKZip archive archive.zip.

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,

ditto foo bar

will copy the contents of foo into bar, whereas

cp -r foo bar

copies foo itself into bar. Though this is not a bug, some may consider this bug-like behavior. −−keepParent for non-archive copies will eventually alleviate this problem.

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) macOS 14.0 March 29, 2023 DITTO(1)