annotate gcp.1 @ 66:d04377706f48 default tip

update about's gcp's page
author Goffi <goffi@goffi.org>
date Tue, 21 Jun 2011 15:12:41 +0200
parents f4c7aa723870
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
1 .\" Hey, EMACS: -*- nroff -*-
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
2 .\" First parameter, NAME, should be all caps
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
4 .\" other parameters are allowed: see man(7), man(1)
48
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
5 .TH GCP 1 "June 04, 2011"
42
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
6 .\" Please adjust this date whenever revising the manpage.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
7 .\"
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
8 .\" Some roff macros, for reference:
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
9 .\" .nh disable hyphenation
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
10 .\" .hy enable hyphenation
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
11 .\" .ad l left justify
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
12 .\" .ad b justify to both left and right margins
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
13 .\" .nf disable filling
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
14 .\" .fi enable filling
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
15 .\" .br insert line break
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
16 .\" .sp <n> insert n+1 empty lines
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
17 .\" for manpage-specific macros, see man(7)
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
18 .SH NAME
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
19 gcp \- Advanced command-line file copier
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
20 .SH SYNOPSIS
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
21 .B gcp
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
22 .RI [ OPTIONS ]
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
23 .I FILE DEST
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
24 .br
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
25 .B gcp
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
26 .RI [ OPTIONS ]
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
27 .I FILE1
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
28 .RI [ FILE2 ... ]
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
29 .I DEST-DIR
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
30 .SH DESCRIPTION
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
31 This manual page documents briefly the
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
32 .B gcp
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
33 command.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
34 .PP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
35 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
36 .\" \fI<whatever>\fP escape sequences to invode bold face and italics,
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
37 .\" respectively.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
38 \fBgcp\fP is a file copier, loosely inspired by cp, but with high level functionalities like:
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
39 \- transfer progression indication
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
40 \- continuous copying when there is an issue: it skips the problematic file and goes on
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
41 \- copy status logging: which files were effectively copied
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
42 \- name mangling to handle target filesystem limitations (e.g. removing incompatible chars like "?" or "*" on vfat)
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
43 \- forced copy serialization: new files to copy are added to a global queue to avoid hard drive head seeks
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
44 \- transfer list management: gcp can save a list of files to copy and reuse it later
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
45 \- approximate option compatibility with cp (approximate because the behaviour is not exactly the same, see below)
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
46 .SH OPTIONS
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
47 These programs follow the usual GNU command line syntax, with long
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
48 options starting with two dashes (`-').
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
49 By default, calling gcp is equivalent to calling gcp \-\-preserve=mode,ownership,timestamps.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
50 .PP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
51 A summary of options is included below.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
52 .SS "General options"
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
53 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
54 .B \-\-version
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
55 Show version of program and exit.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
56 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
57 .B \-h, \-\-help
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
58 Show summary of options.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
59 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
60 .B \-r, \-\-recursive
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
61 Copy directories recursively.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
62 .TP
48
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
63 .B \-L, \-\-dereference
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
64 always follow symbolic links in sources
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
65 .TP
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
66 .B \-P, \-\-no\-dereference
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
67 never follow symbolic links in sources
d26ffbbcbdad updated man page (added dereference and no-dereference options description)
Goffi <goffi@goffi.org>
parents: 42
diff changeset
68 .TP
42
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
69 .B \-f, \-\-force
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
70 Overwrite existing files.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
71 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
72 .B \-\-preserve=PRESERVE
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
73 Keep specified attributes. Attributes can be mode, ownership and timestamps.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
74 When several attributes are passed, they need to be separated by commas. Note
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
75 that timestamps preservation has some limits, see section LIMITS.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
76 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
77 .B \-\-no\-fs\-fix
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
78 Don't fix file system naming incompatibilities.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
79 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
80 .B \-\-no\-progress
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
81 Disable progress bar.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
82 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
83 .B \-v, \-\-verbose
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
84 Display what is being done.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
85 .SS "Sources saving"
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
86 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
87 .B \-\-sources\-save=SOURCES_SAVE
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
88 Save the list of source files in a list named SOURCES_SAVE.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
89 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
90 .B \-\-sources\-replace=SOURCES_REPLACE
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
91 Save the list of source files in a list named SOURCES_REPLACE and
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
92 replace it if it already exists.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
93 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
94 .B \-\-sources\-load=SOURCES_LOAD
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
95 Reuse the list of source file named SOURCES_LOAD.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
96 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
97 .B \-\-sources\-del=SOURCES_DEL
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
98 Delete the list of source files named SOURCES_DEL.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
99 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
100 .B \-\-sources\-list
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
101 List the names of source file lists.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
102 .TP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
103 .B \-\-sources\-full\-list
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
104 List the names of source file lists, including their content.
58
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
105 .SH EXIT STATUS
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
106 The exit status can be:
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
107 .IP \[bu] 2
65
Goffi <goffi@goffi.org>
parents: 58
diff changeset
108 \fB0\fP if files have been copied correctly or if another instance of gcp is already running and will do the copy.
58
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
109 .IP \[bu]
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
110 \fB1\fP if at least one file has not been copied, or if something went wrong.
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
111 .IP \[bu]
58091eac8c8e exit status updated and shown in manpage
Goffi <goffi@goffi.org>
parents: 48
diff changeset
112 \fB2\fP if all files have been copied but with some issues
42
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
113 .SH LIMITS
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
114 Timestamps preservation with \-\-preserve option is limited by the os python
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
115 module on POSIX systems. Currently, python only returns timestamps in float
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
116 format, which is a smaller precision than what POSIX provides. Progress on this
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
117 issue can be seen at http://bugs.python.org/issue11457.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
118 .SH SEE ALSO
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
119 .BR cp (1).
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
120 .br
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
121 .SH AUTHOR
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
122 gcp was written by Jérôme Poisson <goffi@goffi.org>.
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
123 .PP
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
124 This manual page was written by Thomas Preud'homme <robotux@celest.fr>,
671d8c70a84c manpage
Thomas Preud'homme <thomas.preudhomme@celest.fr>
parents:
diff changeset
125 for the Debian project (and may be used by others).