Browse files

* new manpage auto-formatter

* s3cmd.1: Updated using the above helper script
* Warn if manpage is too old.

git-svn-id: 830e0280-6d2a-0410-9c65-932aecc39d9d
  • Loading branch information...
mludvig committed Nov 12, 2010
1 parent 96222f5 commit 593ef06000ad6be78fe69d7a0e782cdbcc90d17c
Showing with 383 additions and 119 deletions.
  1. +6 −0 ChangeLog
  2. +185 −0
  3. +184 −119 s3cmd.1
  4. +8 −0
@@ -1,3 +1,9 @@
+2010-11-12 Michal Ludvig <>
+ * new manpage auto-formatter
+ * s3cmd.1: Updated using the above helper script
+ * Warn if manpage is too old.
2010-10-27 Michal Ludvig <>
*, testsuite.tar.gz: Keep the testsuite in
@@ -0,0 +1,185 @@
+# Format s3cmd.1 manpage
+# Usage:
+# s3cmd --help | > s3cmd.1
+use strict;
+my $commands = "";
+my $cfcommands = "";
+my $options = "";
+while (<>) {
+ if (/^Commands:/) {
+ while (<>) {
+ last if (/^\s*$/);
+ my ($desc, $cmd, $cmdline);
+ ($desc = $_) =~ s/^\s*(.*?)\s*$/$1/;
+ ($cmdline = <>) =~ s/^\s*s3cmd (.*?) (.*?)\s*$/s3cmd \\fB$1\\fR \\fI$2\\fR/;
+ $cmd = $1;
+ if ($cmd =~ /^cf/) {
+ $cfcommands .= ".TP\n$cmdline\n$desc\n";
+ } else {
+ $commands .= ".TP\n$cmdline\n$desc\n";
+ }
+ }
+ }
+ if (/^Options:/) {
+ my ($opt, $desc);
+ while (<>) {
+ last if (/^\s*$/);
+ $_ =~ s/\s*(.*?)\s*$/$1/;
+ $desc = "";
+ $opt = "";
+ if (/^(-.*)/) {
+ $opt = $1;
+ if ($opt =~ / /) {
+ ($opt, $desc) = split(/\s\s+/, $opt, 2);
+ }
+ $opt =~ s/(-[^ ,=]+)/\\fB$1\\fR/g;
+ $opt =~ s/-/\\-/g;
+ $options .= ".TP\n$opt\n";
+ } else {
+ $desc .= $_;
+ }
+ if ($desc) {
+ $options .= "$desc\n";
+ }
+ }
+ }
+print "
+.TH s3cmd 1
+s3cmd \\- tool for managing Amazon S3 storage space and Amazon CloudFront content delivery network
+.B s3cmd
+.B s3cmd
+is a command line client for copying files to/from
+Amazon S3 (Simple Storage Service) and performing other
+related tasks, for instance creating and removing buckets,
+listing objects, etc.
+.B s3cmd
+can do several \\fIactions\\fR specified by the following \\fIcommands\\fR.
+Commands for CloudFront management
+Some of the below specified options can have their default
+values set in
+.B s3cmd
+config file (by default \$HOME/.s3cmd). As it's a simple text file
+feel free to open it with your favorite text editor and do any
+changes you like.
+One of the most powerful commands of \\fIs3cmd\\fR is \\fBs3cmd sync\\fR used for
+synchronising complete directory trees to or from remote S3 storage. To some extent
+\\fBs3cmd put\\fR and \\fBs3cmd get\\fR share a similar behaviour with \\fBsync\\fR.
+Basic usage common in backup scenarios is as simple as:
+ s3cmd sync /local/path/ s3://test-bucket/backup/
+This command will find all files under /local/path directory and copy them
+to corresponding paths under s3://test-bucket/backup on the remote side.
+For example:
+ /local/path/\\fBfile1.ext\\fR \\-> s3://bucket/backup/\\fBfile1.ext\\fR
+ /local/path/\\fBdir123/file2.bin\\fR \\-> s3://bucket/backup/\\fBdir123/file2.bin\\fR
+However if the local path doesn't end with a slash the last directory's name
+is used on the remote side as well. Compare these with the previous example:
+ s3cmd sync /local/path s3://test-bucket/backup/
+will sync:
+ /local/\\fBpath/file1.ext\\fR \\-> s3://bucket/backup/\\fBpath/file1.ext\\fR
+ /local/\\fBpath/dir123/file2.bin\\fR \\-> s3://bucket/backup/\\fBpath/dir123/file2.bin\\fR
+To retrieve the files back from S3 use inverted syntax:
+ s3cmd sync s3://test-bucket/backup/ /tmp/restore/
+that will download files:
+ s3://bucket/backup/\\fBfile1.ext\\fR \\-> /tmp/restore/\\fBfile1.ext\\fR
+ s3://bucket/backup/\\fBdir123/file2.bin\\fR \\-> /tmp/restore/\\fBdir123/file2.bin\\fR
+Without the trailing slash on source the behaviour is similar to
+what has been demonstrated with upload:
+ s3cmd sync s3://test-bucket/backup /tmp/restore/
+will download the files as:
+ s3://bucket/\\fBbackup/file1.ext\\fR \\-> /tmp/restore/\\fBbackup/file1.ext\\fR
+ s3://bucket/\\fBbackup/dir123/file2.bin\\fR \\-> /tmp/restore/\\fBbackup/dir123/file2.bin\\fR
+All source file names, the bold ones above, are matched against \\fBexclude\\fR
+rules and those that match are then re\\-checked against \\fBinclude\\fR rules to see
+whether they should be excluded or kept in the source list.
+For the purpose of \\fB\\-\\-exclude\\fR and \\fB\\-\\-include\\fR matching only the
+bold file names above are used. For instance only \\fBpath/file1.ext\\fR is tested
+against the patterns, not \\fI/local/\\fBpath/file1.ext\\fR
+Both \\fB\\-\\-exclude\\fR and \\fB\\-\\-include\\fR work with shell-style wildcards (a.k.a. GLOB).
+For a greater flexibility s3cmd provides Regular-expression versions of the two exclude options
+named \\fB\\-\\-rexclude\\fR and \\fB\\-\\-rinclude\\fR.
+The options with ...\\fB\\-from\\fR suffix (eg \\-\\-rinclude\\-from) expect a filename as
+an argument. Each line of such a file is treated as one pattern.
+There is only one set of patterns built from all \\fB\\-\\-(r)exclude(\\-from)\\fR options
+and similarly for include variant. Any file excluded with eg \\-\\-exclude can
+be put back with a pattern found in \\-\\-rinclude\\-from list.
+Run s3cmd with \\fB\\-\\-dry\\-run\\fR to verify that your rules work as expected.
+Use together with \\fB\\-\\-debug\\fR get detailed information
+about matching file names against exclude and include rules.
+For example to exclude all files with \".jpg\" extension except those beginning with a number use:
+ \\-\\-exclude '*.jpg' \\-\\-rinclude '[0-9].*\\.jpg'
+For the most up to date list of options run
+.B s3cmd \\-\\-help
+For more info about usage, examples and other related info visit project homepage at
+Written by Michal Ludvig <mludvig\>
+Prefered way to get support is our mailing list:
+.I s3tools\\-general\
+Report bugs to
+.I s3tools\\-bugs\
+Copyright \\(co 2007,2008,2009,2010 Michal Ludvig <>
+This is free software. You may redistribute copies of it under the terms of
+the GNU General Public License version 2 <>.
+There is NO WARRANTY, to the extent permitted by law.
Oops, something went wrong.

0 comments on commit 593ef06

Please sign in to comment.