Re: [PATCH] Fix file mark handling and sort side-effects in git.el

@@ -23,8 +23,33 @@

 ;; This file contains an interface for the git version control
 ;; system. It provides easy access to the most frequently used git
-;; commands. The user interface is as far as possible identical to
-;; that of the PCL-CVS mode.
+;; commands. The user interface intensionally hides some of the full
+;; interface provided by the git command. This was done in order to
+;; keep the user interface similar to other Emacs SCM interface
+;; modes, such as the PCL-CVS mode. For example, it is possible using
+;; git directly from the command-line to do partial checkins such as:
+;;
+;;  - Make a first edit to an git-controlled file
+;;
+;;  - Add the file to the git index with the "git add" command.
+;;
+;;  - Make a second edit to that same file
+;;
+;;  - Checkin the change using the "git commit" command, which
+;;    results in the first edit being committed, but not the second.
+;;
+;; The Emacs Git interface as provided by the git-status command
+;; herein simplifies the checkin sequence by hiding the git index
+;; from the user. Instead, the buffer git-status shows will only show
+;; that the file has been modified, even if some of the modifications
+;; are not yet added to the git index. Only files not yet known to
+;; git have to be added using the "a" keybinding one time (i.e., you
+;; don't have to remember to re-add the second change as required by
+;; git in the example above). To commit, you mark multiple files in
+;; the git-status buffer using the "m" keybinding, and then commit
+;; those files with the "c" binding. Then git-status will insure that
+;; all edits made to those marked files are silently added to the git index
+;; before git commit is executed.
 ;;
 ;; To install: put this file on the load-path and place the following
 ;; in your .emacs file: