stgit.el: Document stgit-select properly
[stgit] / contrib / stgit.el
index 9bbc87d..3d6be1f 100644 (file)
@@ -68,8 +68,12 @@ directory DIR or `default-directory'"
         (start (point))
         (name (stgit-patch-name patch)))
     (case name
-       (:index (insert (propertize "  Index" 'face 'italic)))
-       (:work (insert (propertize "  Work tree" 'face 'italic)))
+       (:index (insert "  "
+                       (propertize "Index"
+                                   'face 'stgit-index-work-tree-title-face)))
+       (:work  (insert "  "
+                       (propertize "Work tree"
+                                   'face 'stgit-index-work-tree-title-face)))
        (t (insert (case status
                     ('applied "+")
                     ('top ">")
@@ -175,15 +179,36 @@ Returns nil if there was no output."
   (when stgit-worktree-node
     (ewoc-invalidate (car stgit-worktree-node) (cdr stgit-worktree-node))))
 
+(defun stgit-run-series-insert-index (ewoc)
+  (setq index-node    (cons ewoc (ewoc-enter-last ewoc
+                                                  (make-stgit-patch
+                                                   :status 'index
+                                                   :name :index
+                                                   :desc nil
+                                                   :empty nil)))
+        worktree-node (cons ewoc (ewoc-enter-last ewoc
+                                                  (make-stgit-patch
+                                                   :status 'work
+                                                   :name :work
+                                                   :desc nil
+                                                   :empty nil)))))
+
 (defun stgit-run-series (ewoc)
-  (let ((first-line t))
+  (setq stgit-index-node nil
+        stgit-worktree-node nil)
+  (let ((inserted-index (not stgit-show-worktree))
+        index-node
+        worktree-node
+        all-patchsyms)
     (with-temp-buffer
       (let ((exit-status (stgit-run-silent "series" "--description" "--empty")))
         (goto-char (point-min))
         (if (not (zerop exit-status))
             (cond ((looking-at "stg series: \\(.*\\)")
+                   (setq inserted-index t)
                    (ewoc-set-hf ewoc (car (ewoc-get-hf ewoc))
-                                "-- not initialized (run M-x stgit-init)"))
+                                (substitute-command-keys
+                                 "-- not initialized; run \\[stgit-init]")))
                   ((looking-at ".*")
                    (error "Error running stg: %s"
                           (match-string 0))))
@@ -194,30 +219,30 @@ Returns nil if there was no output."
             (let* ((state-str (match-string 2))
                    (state (cond ((string= state-str ">") 'top)
                                 ((string= state-str "+") 'applied)
-                                ((string= state-str "-") 'unapplied))))
+                                ((string= state-str "-") 'unapplied)))
+                   (name (intern (match-string 4)))
+                   (desc (match-string 5))
+                   (empty (string= (match-string 1) "0")))
+              (unless inserted-index
+                (when (or (eq stgit-show-worktree-mode 'top)
+                          (and (eq stgit-show-worktree-mode 'center)
+                               (eq state 'unapplied)))
+                  (setq inserted-index t)
+                  (stgit-run-series-insert-index ewoc)))
+              (setq all-patchsyms (cons name all-patchsyms))
               (ewoc-enter-last ewoc
                                (make-stgit-patch
                                 :status state
-                                :name (intern (match-string 4))
-                                :desc (match-string 5)
-                                :empty (string= (match-string 1) "0"))))
-            (setq first-line nil)
-            (forward-line 1)))))
-    (if stgit-show-worktree
-        (setq stgit-index-node (cons ewoc (ewoc-enter-last ewoc
-                                                           (make-stgit-patch
-                                                            :status 'index
-                                                            :name :index
-                                                            :desc nil
-                                                            :empty nil)))
-              stgit-worktree-node (cons ewoc (ewoc-enter-last ewoc
-                                                              (make-stgit-patch
-                                                               :status 'work
-                                                               :name :work
-                                                               :desc nil
-                                                               :empty nil))))
-      (setq stgit-worktree-node nil))))
-
+                                :name   name
+                                :desc   desc
+                                :empty  empty)))
+            (forward-line 1))))
+      (unless inserted-index
+        (stgit-run-series-insert-index ewoc)))
+    (setq stgit-index-node    index-node
+          stgit-worktree-node worktree-node
+          stgit-marked-patches (intersection stgit-marked-patches
+                                             all-patchsyms))))
 
 (defun stgit-reload ()
   "Update the contents of the StGit buffer."
@@ -306,6 +331,13 @@ Returns nil if there was no output."
   "StGit mode face used for permission changes."
   :group 'stgit)
 
+(defface stgit-index-work-tree-title-face
+  '((((supports :slant italic)) :slant italic)
+    (t :inherit bold))
+  "StGit mode face used for the \"Index\" and \"Work tree\" titles"
+  :group 'stgit)
+
+
 (defcustom stgit-expand-find-copies-harder
   nil
   "Try harder to find copied files when listing patches.
@@ -522,7 +554,10 @@ at point."
   (move-to-column (stgit-goal-column)))
 
 (defun stgit-select ()
-  "Expand or collapse the current entry"
+  "With point on a patch, toggle showing files in the patch.
+
+With point on a file, open the associated file. Opens the target
+file for (applied) copies and renames."
   (interactive)
   (case (get-text-property (point) 'entry-type)
     ('patch
@@ -656,7 +691,7 @@ Commands:
   (use-local-map stgit-mode-map)
   (set (make-local-variable 'list-buffers-directory) default-directory)
   (set (make-local-variable 'stgit-marked-patches) nil)
-  (set (make-local-variable 'stgit-expanded-patches) nil)
+  (set (make-local-variable 'stgit-expanded-patches) (list :work :index))
   (set (make-local-variable 'stgit-show-worktree) stgit-default-show-worktree)
   (set (make-local-variable 'stgit-index-node) nil)
   (set (make-local-variable 'stgit-worktree-node) nil)
@@ -1244,6 +1279,20 @@ With prefix argument, refresh the marked patch or the patch under point."
     (stgit-refresh-git-status))
   (stgit-reload))
 
+(defcustom stgit-show-worktree-mode 'center
+  "This variable controls where the \"Index\" and \"Work tree\"
+will be shown on in the buffer.
+
+It can be set to 'top (above all patches), 'center (show between
+applied and unapplied patches), and 'bottom (below all patches).
+
+See also `stgit-show-worktree'."
+  :type '(radio (const :tag "above all patches (top)" top)
+                (const :tag "between applied and unapplied patches (center)"
+                       center)
+                (const :tag "below all patches (bottom)" bottom))
+  :group 'stgit)
+
 (defcustom stgit-default-show-worktree
   nil
   "Set to non-nil to by default show the working tree in a new stgit buffer.
@@ -1253,15 +1302,18 @@ This value is used as the default value for `stgit-show-worktree'."
   :group 'stgit)
 
 (defvar stgit-show-worktree nil
-  "Show work tree and index in the stgit buffer.
+  "If nil, inhibit showing work tree and index in the stgit buffer.
 
-See `stgit-default-show-worktree' for its default value.")
+See also `stgit-show-worktree-mode'.")
 
 (defun stgit-toggle-worktree (&optional arg)
   "Toggle the visibility of the work tree.
 With arg, show the work tree if arg is positive.
 
-Its initial setting is controlled by `stgit-default-show-worktree'."
+Its initial setting is controlled by `stgit-default-show-worktree'.
+
+`stgit-show-worktree-mode' controls where on screen the index and
+work tree will show up."
   (interactive)
   (setq stgit-show-worktree
         (if (numberp arg)