Update/rework manpage

This commit is contained in:
Matteo Cypriani 2018-10-14 20:23:25 +02:00
parent 43da9301fa
commit 81bd453526
1 changed files with 103 additions and 56 deletions

159
gcp.1
View File

@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps .\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1) .\" other parameters are allowed: see man(7), man(1)
.TH GCP 1 "June 04, 2011" .TH GCP 1 "October 14, 2018"
.\" Please adjust this date whenever revising the manpage. .\" Please adjust this date whenever revising the manpage.
.\" .\"
.\" Some roff macros, for reference: .\" Some roff macros, for reference:
@ -15,6 +15,9 @@
.\" .br insert line break .\" .br insert line break
.\" .sp <n> insert n+1 empty lines .\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7) .\" for manpage-specific macros, see man(7)
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
.SH NAME .SH NAME
gcp \- Advanced command-line file copier gcp \- Advanced command-line file copier
.SH SYNOPSIS .SH SYNOPSIS
@ -28,77 +31,109 @@ gcp \- Advanced command-line file copier
.RI [ FILE2 ... ] .RI [ FILE2 ... ]
.I DEST-DIR .I DEST-DIR
.SH DESCRIPTION .SH DESCRIPTION
This manual page documents briefly the \fBgcp\fP is a file copier, loosely inspired by cp, but with high level
.B gcp functionalities like:
command. .IP \(bu 2
.PP transfer progression indication
.\" TeX users may be more comfortable with the \fB<whatever>\fP and .IP \(bu
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, continuous copying when there is an issue: it skips the problematic file and
.\" respectively. goes on
\fBgcp\fP is a file copier, loosely inspired by cp, but with high level functionalities like: .IP \(bu
\- transfer progression indication copy status logging: which files were effectively copied
\- continuous copying when there is an issue: it skips the problematic file and goes on .IP \(bu
\- copy status logging: which files were effectively copied name mangling to handle target filesystem limitations (e.g. removing
\- name mangling to handle target filesystem limitations (e.g. removing incompatible chars like "?" or "*" on vfat) incompatible chars like "?" or "*" on FAT filesystems)
\- forced copy serialization: new files to copy are added to a global queue to avoid hard drive head seeks .IP \(bu
\- transfer list management: gcp can save a list of files to copy and reuse it later forced copy serialization: new files to copy are added to a global queue to
\- approximate option compatibility with cp (approximate because the behaviour is not exactly the same, see below) avoid hard drive head seeks
.IP \(bu
transfer list management: gcp can save a list of files to copy and reuse it
later
.IP \(bu
approximate option compatibility with cp (approximate because the behaviour is
not exactly the same, see below)
.SH OPTIONS .SH OPTIONS
These programs follow the usual GNU command line syntax, with long These programs follow the usual GNU command line syntax, with long
options starting with two dashes (`-'). options starting with two dashes (`-').
By default, calling gcp is equivalent to calling gcp \-\-preserve=mode,ownership,timestamps.
.PP .PP
A summary of options is included below. A summary of options is included below.
.SS "General options" .SS General options
.TP
.B \-\-version
Show version of program and exit.
.TP .TP
.B \-h, \-\-help .B \-h, \-\-help
Show summary of options. Show summary of options.
.TP .TP
.B \-r, \-R, \-\-recursive .B \-V, \-\-version
Copy directories recursively. Show program version and copyright information and exit.
.TP .SS cp-like options
.B \-L, \-\-dereference
always follow symbolic links in sources
.TP
.B \-P, \-\-no\-dereference
never follow symbolic links in sources
.TP .TP
.B \-f, \-\-force .B \-f, \-\-force
Overwrite existing files. Overwrite existing files.
.TP .TP
.B \-L, \-\-dereference
Always follow symbolic links in sources.
.TP
.B \-P, \-\-no\-dereference
Never follow symbolic links in sources.
.TP
.B \-p .B \-p
Same as \-\-preserve=mode,ownership,timestamps Same as \fB\-\-preserve=mode,ownership,timestamps\fP
.TP .TP
.B \-\-preserve=PRESERVE .B \-\-preserve=<\fIattributes\fP>
Keep specified attributes. Attributes can be mode, ownership and timestamps. Preserve specified attributes. Attributes can be \fImode\fP, \fIownership\fP
When several attributes are passed, they need to be separated by commas. Note and \fItimestamps\fP.
that timestamps preservation has some limits, see section LIMITATIONS. When several attributes are passed, they need to be separated by commas.
Please note that timestamps preservation has some limits, see section
\fILIMITATIONS\fP.
.TP .TP
.B \-\-no\-fs\-fix .B \-r, \-R, \-\-recursive
Don't fix file system naming incompatibilities. Copy directories recursively.
.TP
.B \-\-no\-progress
Disable progress bar.
.TP .TP
.B \-v, \-\-verbose .B \-v, \-\-verbose
Display what is being done. Display what is being done.
.SS "Sources saving" .SS gcp-specific options
.TP .TP
.B \-\-sources\-save=SOURCES_SAVE .B \-\-fix\-filenames=<\fIforce\fP|\fIauto\fP|\fIno\fP>
Save the list of source files in a list named SOURCES_SAVE. gcp has the ability to modify the destination file name if the target file
system would not accept the original file name.
Offending characters will be replaced with similar-looking ones.
.IP
This option accept the following values:
.RS
.TP .TP
.B \-\-sources\-replace=SOURCES_REPLACE \fIauto\fP (default)
Save the list of source files in a list named SOURCES_REPLACE and gcp will attempt to be smart, i.e. detect incompatibilities and fix them as-needed.
replace it if it already exists.
.TP .TP
.B \-\-sources\-load=SOURCES_LOAD \fIforce\fP
Reuse the list of source file named SOURCES_LOAD. Always fix file names that could cause problems on any known filesystem or OS.
This is useful e.g. with NTFS, see \fINOTE ON NTFS\fP below.
.TP .TP
.B \-\-sources\-del=SOURCES_DEL \fIno\fP
Delete the list of source files named SOURCES_DEL. Renaming is disabled entirely.
.RE
.IP
Currently, gcp is only aware of FAT incompatibilities:
\'\\\', \':\', \'*\', \'?\', \'"\', \'<\', \'>\' and \'|\'.
.TP
.B \-\-no\-fs\-fix (DEPRECATED)
Same as \fB\-\-fix\-filenames=no\fP.
This option will be removed in a future release.
.TP
.B \-\-no\-progress
Disable progress bar.
.SS Sources saving
.TP
.B \-\-sources\-save=\fISOURCES\fP
Save the list of source files in a list named \fISOURCES\fP.
.TP
.B \-\-sources\-replace=\fISOURCES\fP
Save the list of source files in a list named \fISOURCES\fP;
the file is overwritten it already exists.
.TP
.B \-\-sources\-load=\fISOURCES\fP
Use the list of source files named \fISOURCES\fP.
.TP
.B \-\-sources\-del=\fISOURCES\fP
Delete the list of source files named \fISOURCES\fP.
.TP .TP
.B \-\-sources\-list .B \-\-sources\-list
List the names of source file lists. List the names of source file lists.
@ -108,21 +143,33 @@ List the names of source file lists, including their content.
.SH EXIT STATUS .SH EXIT STATUS
The exit status can be: The exit status can be:
.IP \[bu] 2 .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. \fB0\fP if files have been copied correctly or if another instance of gcp is
already running and will do the copy.
.IP \[bu] .IP \[bu]
\fB1\fP if at least one file has not been copied, or if something went wrong. \fB1\fP if at least one file has not been copied, or if something went wrong.
.IP \[bu] .IP \[bu]
\fB2\fP if all files have been copied but with some issues \fB2\fP if all files have been copied but with some issues
.SH LIMITATIONS .SH LIMITATIONS
Timestamps preservation with \-\-preserve option is limited by the os python Timestamps preservation with \fB\-\-preserve\fP option is limited by the
module on POSIX systems. Currently, python only returns timestamps in float \fIos\fP Python module on POSIX systems. Currently, Python only returns
format, which is a smaller precision than what POSIX provides. Progress on this timestamps in float format, which is a smaller precision than what POSIX
issue can be seen at http://bugs.python.org/issue11457. provides. Progress on this issue can be seen at
http://bugs.python.org/issue11457.
.PP
The \fB\-\-preserve\fP option cannot currently be used without an attribute
list (\fBgcp \-\-preserve foo bar\fP will behave as \fBgcp \-\-preserve=foo
bar\fP). Use the \fB\-p\fP switch instead.
.SH NOTE ON NTFS
NTFS will not enforce the same file name limitations than FAT, but files that
would not be accepted on a FAT filesystem will still cause problems on Windows.
Hence, it is recommended to use \-\-fix-filenames=force when copying to NTFS
(when Windows compatibility is desired, anyway).
.SH SEE ALSO .SH SEE ALSO
.BR cp (1). .BR cp (1).
.br .br
.SH AUTHOR .SH AUTHOR
gcp was written by Jérôme Poisson <goffi@goffi.org>. gcp was written by Jérôme Poisson <goffi@goffi.org>.
It is currently maintained by Matteo Cypriani <mcy@lm7.fr>.
.PP .PP
This manual page was written by Thomas Preud'homme <robotux@celest.fr>, This manual page was initially written by Thomas Preud'homme
for the Debian project (and may be used by others). <robotux@celest.fr> for the Debian project (and may be used by others).