.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH GCP 1 "June 04, 2011"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
gcp \- Advanced command-line file copier
.SH SYNOPSIS
.B gcp
.RI [ OPTIONS ]
.I FILE DEST
.br
.B gcp
.RI [ OPTIONS ]
.I FILE1
.RI [ FILE2 ... ]
.I DEST-DIR
.SH DESCRIPTION
This manual page documents briefly the
.B gcp
command.
.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
\fBgcp\fP is a file copier, loosely inspired by cp, but with high level functionalities like:
 \- transfer progression indication
 \- continuous copying when there is an issue: it skips the problematic file and goes on
 \- copy status logging: which files were effectively copied
 \- name mangling to handle target filesystem limitations (e.g. removing incompatible chars like "?" or "*" on vfat)
 \- forced copy serialization: new files to copy are added to a global queue to avoid hard drive head seeks
 \- transfer list management: gcp can save a list of files to copy and reuse it later
 \- approximate option compatibility with cp (approximate because the behaviour is not exactly the same, see below)
.SH OPTIONS
These programs follow the usual GNU command line syntax, with long
options starting with two dashes (`-').
By default, calling gcp is equivalent to calling gcp \-\-preserve=mode,ownership,timestamps.
.PP
A summary of options is included below.
.SS "General options"
.TP
.B \-\-version
Show version of program and exit.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-r, \-\-recursive
Copy directories recursively.
.TP
.B \-L, \-\-dereference
always follow symbolic links in sources
.TP
.B \-P, \-\-no\-dereference
never follow symbolic links in sources
.TP
.B \-f, \-\-force
Overwrite existing files.
.TP
.B \-\-preserve=PRESERVE
Keep specified attributes. Attributes can be mode, ownership and timestamps.
When several attributes are passed, they need to be separated by commas. Note
that timestamps preservation has some limits, see section LIMITS.
.TP
.B \-\-no\-fs\-fix
Don't fix file system naming incompatibilities.
.TP
.B \-\-no\-progress
Disable progress bar.
.TP
.B \-v, \-\-verbose
Display what is being done.
.SS "Sources saving"
.TP
.B \-\-sources\-save=SOURCES_SAVE
Save the list of source files in a list named SOURCES_SAVE.
.TP
.B \-\-sources\-replace=SOURCES_REPLACE
Save the list of source files in a list named SOURCES_REPLACE and
replace it if it already exists.
.TP
.B \-\-sources\-load=SOURCES_LOAD
Reuse the list of source file named SOURCES_LOAD.
.TP
.B \-\-sources\-del=SOURCES_DEL
Delete the list of source files named SOURCES_DEL.
.TP
.B \-\-sources\-list
List the names of source file lists.
.TP
.B \-\-sources\-full\-list
List the names of source file lists, including their content.
.SH EXIT STATUS
The exit status can be:
.IP \[bu] 2
\fB0\fP if files have been copied correctly or if another instance of gcp is already running and will do the copy.
.IP \[bu]
\fB1\fP if at least one file has not been copied, or if something went wrong.
.IP \[bu]
\fB2\fP if all files have been copied but with some issues
.SH LIMITS
Timestamps preservation with \-\-preserve option is limited by the os python
module on POSIX systems. Currently, python only returns timestamps in float
format, which is a smaller precision than what POSIX provides. Progress on this
issue can be seen at http://bugs.python.org/issue11457.
.SH SEE ALSO
.BR cp (1).
.br
.SH AUTHOR
gcp was written by Jérôme Poisson <goffi@goffi.org>.
.PP
This manual page was written by Thomas Preud'homme <robotux@celest.fr>,
for the Debian project (and may be used by others).