Browse Source

Update/rework manpage

tags/0.2.0
Matteo Cypriani 7 months ago
parent
commit
81bd453526
1 changed files with 102 additions and 55 deletions
  1. 102
    55
      gcp.1

+ 102
- 55
gcp.1 View File

@@ -2,7 +2,7 @@
2 2
 .\" First parameter, NAME, should be all caps
3 3
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4 4
 .\" other parameters are allowed: see man(7), man(1)
5
-.TH GCP 1 "June 04, 2011"
5
+.TH GCP 1 "October 14, 2018"
6 6
 .\" Please adjust this date whenever revising the manpage.
7 7
 .\"
8 8
 .\" Some roff macros, for reference:
@@ -15,6 +15,9 @@
15 15
 .\" .br        insert line break
16 16
 .\" .sp <n>    insert n+1 empty lines
17 17
 .\" for manpage-specific macros, see man(7)
18
+.\" TeX users may be more comfortable with the \fB<whatever>\fP and
19
+.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
20
+.\" respectively.
18 21
 .SH NAME
19 22
 gcp \- Advanced command-line file copier
20 23
 .SH SYNOPSIS
@@ -28,77 +31,109 @@ gcp \- Advanced command-line file copier
28 31
 .RI [ FILE2 ... ]
29 32
 .I DEST-DIR
30 33
 .SH DESCRIPTION
31
-This manual page documents briefly the
32
-.B gcp
33
-command.
34
-.PP
35
-.\" TeX users may be more comfortable with the \fB<whatever>\fP and
36
-.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
37
-.\" respectively.
38
-\fBgcp\fP is a file copier, loosely inspired by cp, but with high level functionalities like:
39
- \- transfer progression indication
40
- \- continuous copying when there is an issue: it skips the problematic file and goes on
41
- \- copy status logging: which files were effectively copied
42
- \- name mangling to handle target filesystem limitations (e.g. removing incompatible chars like "?" or "*" on vfat)
43
- \- forced copy serialization: new files to copy are added to a global queue to avoid hard drive head seeks
44
- \- transfer list management: gcp can save a list of files to copy and reuse it later
45
- \- approximate option compatibility with cp (approximate because the behaviour is not exactly the same, see below)
34
+\fBgcp\fP is a file copier, loosely inspired by cp, but with high level
35
+functionalities like:
36
+.IP \(bu 2
37
+transfer progression indication
38
+.IP \(bu
39
+continuous copying when there is an issue: it skips the problematic file and
40
+goes on
41
+.IP \(bu
42
+copy status logging: which files were effectively copied
43
+.IP \(bu
44
+name mangling to handle target filesystem limitations (e.g. removing
45
+incompatible chars like "?" or "*" on FAT filesystems)
46
+.IP \(bu
47
+forced copy serialization: new files to copy are added to a global queue to
48
+avoid hard drive head seeks
49
+.IP \(bu
50
+transfer list management: gcp can save a list of files to copy and reuse it
51
+later
52
+.IP \(bu
53
+approximate option compatibility with cp (approximate because the behaviour is
54
+not exactly the same, see below)
46 55
 .SH OPTIONS
47 56
 These programs follow the usual GNU command line syntax, with long
48 57
 options starting with two dashes (`-').
49
-By default, calling gcp is equivalent to calling gcp \-\-preserve=mode,ownership,timestamps.
50 58
 .PP
51 59
 A summary of options is included below.
52
-.SS "General options"
53
-.TP
54
-.B \-\-version
55
-Show version of program and exit.
60
+.SS General options
56 61
 .TP
57 62
 .B \-h, \-\-help
58 63
 Show summary of options.
59 64
 .TP
60
-.B \-r, \-R, \-\-recursive
61
-Copy directories recursively.
65
+.B \-V, \-\-version
66
+Show program version and copyright information and exit.
67
+.SS cp-like options
68
+.TP
69
+.B \-f, \-\-force
70
+Overwrite existing files.
62 71
 .TP
63 72
 .B \-L, \-\-dereference
64
-always follow symbolic links in sources
73
+Always follow symbolic links in sources.
65 74
 .TP
66 75
 .B \-P, \-\-no\-dereference
67
-never follow symbolic links in sources
68
-.TP
69
-.B \-f, \-\-force
70
-Overwrite existing files.
76
+Never follow symbolic links in sources.
71 77
 .TP
72 78
 .B \-p
73
-Same as \-\-preserve=mode,ownership,timestamps
79
+Same as \fB\-\-preserve=mode,ownership,timestamps\fP
74 80
 .TP
75
-.B \-\-preserve=PRESERVE
76
-Keep specified attributes. Attributes can be mode, ownership and timestamps.
77
-When several attributes are passed, they need to be separated by commas. Note
78
-that timestamps preservation has some limits, see section LIMITATIONS.
81
+.B \-\-preserve=<\fIattributes\fP>
82
+Preserve specified attributes. Attributes can be \fImode\fP, \fIownership\fP
83
+and \fItimestamps\fP.
84
+When several attributes are passed, they need to be separated by commas.
85
+Please note that timestamps preservation has some limits, see section
86
+\fILIMITATIONS\fP.
79 87
 .TP
80
-.B \-\-no\-fs\-fix
81
-Don't fix file system naming incompatibilities.
82
-.TP
83
-.B \-\-no\-progress
84
-Disable progress bar.
88
+.B \-r, \-R, \-\-recursive
89
+Copy directories recursively.
85 90
 .TP
86 91
 .B \-v, \-\-verbose
87 92
 Display what is being done.
88
-.SS "Sources saving"
93
+.SS gcp-specific options
94
+.TP
95
+.B \-\-fix\-filenames=<\fIforce\fP|\fIauto\fP|\fIno\fP>
96
+gcp has the ability to modify the destination file name if the target file
97
+system would not accept the original file name.
98
+Offending characters will be replaced with similar-looking ones.
99
+.IP
100
+This option accept the following values:
101
+.RS
102
+.TP
103
+\fIauto\fP (default)
104
+gcp will attempt to be smart, i.e. detect incompatibilities and fix them as-needed.
105
+.TP
106
+\fIforce\fP
107
+Always fix file names that could cause problems on any known filesystem or OS.
108
+This is useful e.g. with NTFS, see \fINOTE ON NTFS\fP below.
109
+.TP
110
+\fIno\fP
111
+Renaming is disabled entirely.
112
+.RE
113
+.IP
114
+Currently, gcp is only aware of FAT incompatibilities:
115
+\'\\\', \':\', \'*\', \'?\', \'"\', \'<\', \'>\' and \'|\'.
116
+.TP
117
+.B \-\-no\-fs\-fix (DEPRECATED)
118
+Same as \fB\-\-fix\-filenames=no\fP.
119
+This option will be removed in a future release.
120
+.TP
121
+.B \-\-no\-progress
122
+Disable progress bar.
123
+.SS Sources saving
89 124
 .TP
90
-.B \-\-sources\-save=SOURCES_SAVE
91
-Save the list of source files in a list named SOURCES_SAVE.
125
+.B \-\-sources\-save=\fISOURCES\fP
126
+Save the list of source files in a list named \fISOURCES\fP.
92 127
 .TP
93
-.B \-\-sources\-replace=SOURCES_REPLACE
94
-Save the list of source files in a list named SOURCES_REPLACE and
95
-replace it if it already exists.
128
+.B \-\-sources\-replace=\fISOURCES\fP
129
+Save the list of source files in a list named \fISOURCES\fP;
130
+the file is overwritten it already exists.
96 131
 .TP
97
-.B \-\-sources\-load=SOURCES_LOAD
98
-Reuse the list of source file named SOURCES_LOAD.
132
+.B \-\-sources\-load=\fISOURCES\fP
133
+Use the list of source files named \fISOURCES\fP.
99 134
 .TP
100
-.B \-\-sources\-del=SOURCES_DEL
101
-Delete the list of source files named SOURCES_DEL.
135
+.B \-\-sources\-del=\fISOURCES\fP
136
+Delete the list of source files named \fISOURCES\fP.
102 137
 .TP
103 138
 .B \-\-sources\-list
104 139
 List the names of source file lists.
@@ -108,21 +143,33 @@ List the names of source file lists, including their content.
108 143
 .SH EXIT STATUS
109 144
 The exit status can be:
110 145
 .IP \[bu] 2
111
-\fB0\fP if files have been copied correctly or if another instance of gcp is already running and will do the copy.
146
+\fB0\fP if files have been copied correctly or if another instance of gcp is
147
+already running and will do the copy.
112 148
 .IP \[bu]
113 149
 \fB1\fP if at least one file has not been copied, or if something went wrong.
114 150
 .IP \[bu]
115 151
 \fB2\fP if all files have been copied but with some issues
116 152
 .SH LIMITATIONS
117
-Timestamps preservation with \-\-preserve option is limited by the os python
118
-module on POSIX systems. Currently, python only returns timestamps in float
119
-format, which is a smaller precision than what POSIX provides. Progress on this
120
-issue can be seen at http://bugs.python.org/issue11457.
153
+Timestamps preservation with \fB\-\-preserve\fP option is limited by the
154
+\fIos\fP Python module on POSIX systems. Currently, Python only returns
155
+timestamps in float format, which is a smaller precision than what POSIX
156
+provides. Progress on this issue can be seen at
157
+http://bugs.python.org/issue11457.
158
+.PP
159
+The \fB\-\-preserve\fP option cannot currently be used without an attribute
160
+list (\fBgcp \-\-preserve foo bar\fP will behave as \fBgcp \-\-preserve=foo
161
+bar\fP). Use the \fB\-p\fP switch instead.
162
+.SH NOTE ON NTFS
163
+NTFS will not enforce the same file name limitations than FAT, but files that
164
+would not be accepted on a FAT filesystem will still cause problems on Windows.
165
+Hence, it is recommended to use \-\-fix-filenames=force when copying to NTFS
166
+(when Windows compatibility is desired, anyway).
121 167
 .SH SEE ALSO
122 168
 .BR cp (1).
123 169
 .br
124 170
 .SH AUTHOR
125 171
 gcp was written by Jérôme Poisson <goffi@goffi.org>.
172
+It is currently maintained by Matteo Cypriani <mcy@lm7.fr>.
126 173
 .PP
127
-This manual page was written by Thomas Preud'homme <robotux@celest.fr>,
128
-for the Debian project (and may be used by others).
174
+This manual page was initially written by Thomas Preud'homme
175
+<robotux@celest.fr> for the Debian project (and may be used by others).

Loading…
Cancel
Save