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

[Brent Goodrick <bgoodr@gmail.com>]

> There's no manual, and I'm not going to write one, I suck at writing
> documentation. If you would like to contribute one it would certainly be
> welcome.

It's apparent that you are quite articulate in your emails, so I don't
buy the argument that you suck at writing documentation. ;)

Actually, there isn't enough functionality in git.el to write up in a
manual yet. Once there is, then perhaps having a manual might make
sense.

Let's just leave it as adding additional commentary at the top of
git.el that warns future users of the intent behind the user interface
so that you don't have to keep answering this question later on.  To
that end, here is a patch of my attempt at adding an explanatory
comment at the top of git.el (in lieu of a full-blown manual):

diff --git a/contrib/emacs/git.el b/contrib/emacs/git.el
index fcbe2d9..b383f51 100644
--- a/contrib/emacs/git.el
+++ b/contrib/emacs/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:


>
>> However, the *git-status* buffer does properly reflect the two added
>> files by their state being changed to "Added". Since you may have a
>> ton of files that are being added, it probably doesn't make a whole
>> lot of sense to dump a long message into the minibuffer with all of
>> those names.  By the same token, it doesn't make sense to emit one
>> message per file either. Instead, would you be willing to change that
>> message to just state "Added n files" where "n" is the number of files
>> added?
>
> That's exactly what git-success-message already does. The only problem
> is that the list isn't always preserved properly (and that's only a
> cosmetic bug, the operations get carried out correctly).

Agreed.  Thanks for your help!

bg