README: Add lots of new stuff, and some rewriting.

* Make first section a separate 'Overview' section under the title,
  and split it in to subsections.
* Update missing features section.
* Add Install/Invocation, Testing and Authors/History sections.

License stuff will come in as a separate commit.

Author: 0cjs

README.md

@@ -1,33 +1,102 @@
 git-commit-filetree
--------------------
+===================
+
+Overview
+--------
+
+`git-commit-filetree` is a git command that takes an arbitrary tree
+of files (typically not part of a Git repository's working copy) and
+commits that file tree to the end of a given branch. It can be run as a
+standalone script, or installed as a git command.
 
-`git-commit-filetree` is a git command that takes an arbitrary tree of
-files and creates a commit of them appended to a given branch. It can
-also be run as a standalone script.
+Usage: `git commit-filetree <branch> <path>`
 
-Usage:
+### Motivation
 
-    git commit-filetree <branch> <path>
+This command allows you to do builds on one branch of a repo and then
+commit the build output to a separate branch of the same repo. This
+avoids making a second clone of the repo with its own working copy,
+doing the commit there, and then moving the new commit from the second
+repo to the first.
 
-The main purpose of this command is to allow you to commit builds made
-on one branch of a repo to another branch without having to set up a
-second repo and working copy.
+### Usage with Github.io
 
-A classic use case is when you're using your own build system to a
-static website to be hosted on `github.io`. You would check out your
-repo's `master` branch, build your site into an output directory (e.g.,
-`output/site`) and then run `git commit-filetree gh-pages output/site`
-to commit the new version of the site to the `gh-pages` branch. Then a
-`git push --all` will upload both the updated source and updated build
-and github.io will start serving the new version of the site on the
-`gh-pages` branch.
+A classic use case is when you're using your own build system to create
+a static website to be hosted on
+[github.io](https://help.github.com/categories/github-pages-basics/).
+The procedure is as follows:
+
+* Check out your repo's `master` branch (or whichever branch contains your
+  source code and build system).
+* Build your site into an output directory (e.g., `./_site`).
+* Run `git commit-filetree gh-pages ./_site`. This will update the `gh-pages`
+  branch with the new version of the site under the `./_site` directory.
+* `git push --all` to upload your latest source and generated site to Github.
+* Github.io will start serving the new version of the site from the
+  `gh-pages` branch.
 
 Missing Features
 ----------------
 
 The following features are still missing from this version of the
 program.
 
+* Test fixes for Git 2.5.x (or perhaps all of Git 2.x) due to a
+  format change git log's `%d` format.
 * Update the reflog after doing the commit.
 * Add the ability to specify a commit message.
-* A manual page
+  (This should allow a token to substitute the current HEAD commit at
+  the time git-commit-filetree was run, e.g., `%h`.)
+* Manual page.
+
+Installation and Invocation
+---------------------------
+
+The script can be invoked in one of two ways. In both cases,
+you'll need to ensure that the executable bit is set.
+
+* Directly from the command line. E.g.,
+  `./git-commit-filetree mybranch myfiles`.
+* Copy the script to any directory in your path and invoke it through
+  `git commit-filetree mybranch myfiles`.
+
+The second method will allow you to use `git` parameters before the
+`commit-filetree` command, such as `-C`, `--git-dir`, `--work-tree`, and
+so on.
+
+### Usage with Windows
+
+The standard Git installation for Windows includes the Bash shell, and
+so it appears that Windows has everything necessary to run this command.
+However, we've not tried it. If you wish to get it working, we would
+appreciate any feedback you could offer.
+
+Testing
+-------
+
+The test framework uses shell scripts that generate output conforming to
+the [TAP Specification](https://testanything.org/tap-specification.html).
+
+The top-level `Test` script will run the tests using perl's `prove`
+program, which is part of the standard install on most GNU/Linux
+systems. However, you should be able to use other TAP test harnesses
+should the need arise. If you have any difficulty, please feel free to
+contact the authors for help.
+
+Authors and History
+-------------------
+
+* Curt J. Sampson <<cjs@cynic.net>>
+* Nishant Rodrigues <<nishantjr@gmail.com>>
+
+cjs and Nishant together came up with the general idea.
+
+Nishant did the heavy lifting to figure out exactly how to use the
+Git plumbing to get the job done. (It turned out to be a little more
+complex than we'd thought due to Git's propensity to want to stage
+things through an index file rather than just directly create a tree
+object. Perhaps that's for performance reasons in the more general case
+of git use.)
+
+cjs wrote the test framework and tests, and the `git-commit-filetree`
+command framework (error handling, usage messages, etc.).