From d29575246ed79f140ee195e45a7adce96ec87d0c Mon Sep 17 00:00:00 2001
From: "G.raud" <graud@gmx.com>
Date: Fri, 25 Apr 2014 08:56:01 +0200
Subject: [PATCH] README, archives2git: move the examples to the script

Since git-rev-parse prints its own short usage message, the HelpM manual
can be long.
---
 README       | 88 +++++++++++++++++++++++-------------------------------------
 archives2git | 21 ++++++++++++++-
 2 files changed, 54 insertions(+), 55 deletions(-)
 rewrite README (66%)

diff --git a/README b/README
dissimilarity index 66%
index f39c3a2..8999c7d 100644
--- a/README
+++ b/README
@@ -1,54 +1,34 @@
-README for archives2git
-=======================
-
-`archives2git` is intended to recreate a poor-man's history from the (release)
-archives of a project.  It is an sh script that commits the given file archives
-to a Git repository as a series of commits; by default the commit (sub-)trees
-will replicate the contents of their corresponding archive.
-
-For the documentation see the manual of linkpage:archives2git[1] (or the help
-message output), the examples below, then look inside the config file example
-link:archives2gitrc[example] and finally inside the link:archives2git[script].
-
-Examples
---------
-
-Basic usage:
-
-	cd git-repo # may be a subdir of the toplevel of a repo
-	GIT_AUTHOR_NAME="Firstname Lastname" GIT_AUTHOR_EMAIL=user@host \
-	archives2git ../oldproject-?.??.tar.gz
-
-Some possible options:
-
-	archives2git $(ls ../oldproject-*.tgz | sort -V)
-	  --keep-filter 'test x.gitignore = x"$file"'
-	    # keep (only) the .gitignore file
-	  --keep-filter 'echo "$file" | grep -q -f $HOME/filepats'
-	  --rename 'echo "${file%-*}"'
-	    # suppress the version info from the root directory in the archive
-	  --gitadd-arg -f
-	    # allow to add ignored files
-	  --date 'LC_ALL=C date -r "$arch"'
-	    # use the archive modification time as the author date (with GNU date)
-	  --title 'echo "${arch##*/}"'
-	    # do not include the path components in the commit title
-	  --gitci-arg "--edit"
-	    # interactively edit each commit message
-	  --gitfilter $'--subdirectory-filter\noldproject'
-	    # keep only the files of the project in the root of the tree
-	  --gitfilter $'--tree-filter\nmv oldproject/.* .; mv oldproject/* .'
-	    # move the project's files out of their subdir (while keeping other files)
-
-Limitions & Bugs
-----------------
-
-* Trailing newlines in file names are not supported.
-
-Dependencies
-------------
-
-* POSIX `sh`
-* `mktemp`
-* `aunpack` from link:http://www.nongnu.org/atool/[atool]
-* `git`
+README for archives2git
+=======================
+
+`archives2git` is intended to recreate a poor-man's history from the (release)
+archives of a project.  It is an sh script that commits the given file archives
+to a Git repository as a series of commits; by default the commit (sub-)trees
+will replicate the contents of their corresponding archive.
+
+Resources
+---------
+
+For the documentation see the manual of linkpage:archives2git[1] (or the help
+message output), then look inside the configuration file example
+link:archives2gitrc[.archives2gitrc] and finally inside the
+link:archives2git[script].
+
+Basic usage:
+
+	$ cd git-repo # may be a subdir of the toplevel of a repo
+	$ GIT_AUTHOR_NAME="Firstname Lastname" GIT_AUTHOR_EMAIL=user@host \
+	  archives2git --tag ../oldproject-?.??.tar.gz
+
+Limitions & Bugs
+----------------
+
+* Trailing newlines in file names are not supported.
+
+Dependencies
+------------
+
+* POSIX `sh`
+* `mktemp`
+* `aunpack` from link:http://www.nongnu.org/atool/[atool]
+* `git`
diff --git a/archives2git b/archives2git
index b94cb01..6d79c78 100755
--- a/archives2git
+++ b/archives2git
@@ -41,7 +41,26 @@ FILES
  	~/.archives2gitrc
 		An example file is distributed.
 EXAMPLES
-	See the README.
+	Some possible options:
+	  $ archives2git \$(ls ../oldproject-*.tgz | sort -V) \\
+	    # keep (only) the .gitignore file
+	    --keep-filter 'test x.gitignore = x"\$file"'
+	    --keep-filter 'echo "\$file" | grep -q -f \$HOME/filepats'
+	    # suppress the version info from the root directory in the archive
+	    --rename 'echo "\${file%-*}"'
+	    # allow to add ignored files
+	    --gitadd-arg -f
+	    # use the archive modification time as the author date (with GNU date)
+	    --date 'LC_ALL=C date -r "\$arch"'
+	    # do not include the path components in the commit title
+	    --title 'echo "\${arch##*/}"'
+	    # interactively edit each commit message
+	    --gitci-arg "--edit"
+	    # keep only the files of the project in the root of the tree
+	    --gitfilter $'--subdirectory-filter\noldproject'
+	    # move the project's files out of their subdir (while keeping other files)
+	    --gitfilter $'--tree-filter\nmv oldproject/.* .; mv oldproject/* .'
+	See also the example configuration file.
 AUTHOR
 	$PROGRAM_NAME was written by G.raud Meyer.
 SEE ALSO
-- 
2.11.4.GIT