[nongnu] elpa/git-commit 4ee9c9a 01/11: Add several commands for switching to existing Magit buffers

[ELPA Syncer]

branch: elpa/git-commit
commit 4ee9c9a1981cbc99b93623858edccfe9aee8f7d6
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Add several commands for switching to existing Magit buffers
    
    Closes #4259.
---
 Documentation/RelNotes/3.3.0.org |  8 ++++++
 Documentation/magit.org          | 44 ++++++++++++++++++++++++++++++--
 Documentation/magit.texi         | 54 ++++++++++++++++++++++++++++++++++++++--
 lisp/magit-extras.el             | 45 +++++++++++++++++++++++++++++++++
 lisp/magit-mode.el               |  2 ++
 lisp/magit-status.el             | 23 +++++++++++++++++
 lisp/magit.el                    |  3 +++
 7 files changed, 175 insertions(+), 4 deletions(-)

diff --git a/Documentation/RelNotes/3.3.0.org b/Documentation/RelNotes/3.3.0.org
index 0fc3075..adea68c 100644
--- a/Documentation/RelNotes/3.3.0.org
+++ b/Documentation/RelNotes/3.3.0.org
@@ -15,6 +15,14 @@
   Like most newly added expert arguments they have to be explicitly
   
[[https://magit.vc/manual/transient/Enabling-and-Disabling-Suffixes.html][revealed]].
  #4387
 
+- Added new command ~magit-status-quick~, which shows the status buffer
+  but avoids refreshing it for performance reasons.  #4259
+
+- Added new commands ~magit-display-repository-buffer~ (bound to ~j~ in
+  Magit buffers) and ~magit-switch-to-repository-buffer~ (bound to ~J~)
+  and variants for switching to any existing Magit buffer belonging
+  to the current repository.  #4259
+
 ** Fixes since v3.2.0
 
 - Make ~magit-branch-remote-head~ and ~magit-branch-current~ fall back
diff --git a/Documentation/magit.org b/Documentation/magit.org
index 1f510f1..9577830 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Magit: (magit).
 #+TEXINFO_DIR_DESC: Using Git from Emacs with Magit.
-#+SUBTITLE: for version 3.2.1 (v3.2.1-11-g16316ed16+1)
+#+SUBTITLE: for version 3.2.1 (v3.2.1-13-g0348f1f87+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:3 toc:2
@@ -25,7 +25,7 @@ directly from within Emacs.  While many fine Git clients 
exist, only
 Magit and Git itself deserve to be called porcelains.
 
 #+TEXINFO: @noindent
-This manual is for Magit version 3.2.1 (v3.2.1-11-g16316ed16+1).
+This manual is for Magit version 3.2.1 (v3.2.1-13-g0348f1f87+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li>
@@ -2065,6 +2065,34 @@ that it should be bound globally.  We recommend using 
~C-x g~:
   ~magit-list-repositories~.  It also affects ~magit-status~ (which see)
   in potentially surprising ways (see above).
 
+- Command: magit-status-quick
+
+  This command is an alternative to ~magit-status~ that usually avoids
+  refreshing the status buffer.
+
+  If the status buffer of the current Git repository exists but isn't
+  being displayed in the selected frame, then it is displayed without
+  being refreshed.
+
+  If the status buffer is being displayed in the selected frame,
+  then this command refreshes it.
+
+  Prefix arguments have the same meaning as for ~magit-status~,
+  and additionally cause the buffer to be refresh.
+
+  To use this command add this to your init file:
+
+  #+BEGIN_SRC emacs-lisp
+    (global-set-key (kbd "C-x g") 'magit-status-quick).
+  #+END_SRC
+
+  If you do that and then for once want to redisplay the buffer and
+  also immediately refresh it, then type ~C-x g~ followed by ~g~.
+
+  A possible alternative command is ~magit-display-repository-buffer~.
+  It supports displaying any existing Magit buffer that belongs to the
+  current repository; not just the status buffer.
+
 - Command: ido-enter-magit-status
 
   From an Ido prompt used to open a file, instead drop into
@@ -6900,6 +6928,18 @@ Also see [[man:git-worktree]]
 
 ** Common Commands
 
+- Command: magit-switch-to-repository-buffer
+- Command: magit-switch-to-repository-buffer-other-window
+- Command: magit-switch-to-repository-buffer-other-frame
+- Command: magit-display-repository-buffer
+
+  These commands read any existing Magit buffer that belongs to the
+  current repository from the user and then switch to the selected
+  buffer (without refreshing it).
+
+  The last variant uses ~magit-display-buffer~ to do so and thus
+  respects ~magit-display-buffer-function~.
+
 These are some of the commands that can be used in all buffers whose
 major-modes derive from ~magit-mode~.  There are other common commands
 beside the ones below, but these didn't fit well anywhere else.
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index df73be4..049db74 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Magit User Manual
-@subtitle for version 3.2.1 (v3.2.1-11-g16316ed16+1)
+@subtitle for version 3.2.1 (v3.2.1-13-g0348f1f87+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -53,7 +53,7 @@ directly from within Emacs.  While many fine Git clients 
exist, only
 Magit and Git itself deserve to be called porcelains.
 
 @noindent
-This manual is for Magit version 3.2.1 (v3.2.1-11-g16316ed16+1).
+This manual is for Magit version 3.2.1 (v3.2.1-13-g0348f1f87+1).
 
 @quotation
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@@bernoul.li>
@@ -2809,6 +2809,36 @@ This option controls which repositories are being listed 
by
 in potentially surprising ways (see above).
 @end defopt
 
+@cindex magit-status-quick
+@deffn Command magit-status-quick
+
+This command is an alternative to @code{magit-status} that usually avoids
+refreshing the status buffer.
+
+If the status buffer of the current Git repository exists but isn't
+being displayed in the selected frame, then it is displayed without
+being refreshed.
+
+If the status buffer is being displayed in the selected frame,
+then this command refreshes it.
+
+Prefix arguments have the same meaning as for @code{magit-status},
+and additionally cause the buffer to be refresh.
+
+To use this command add this to your init file:
+
+@lisp
+(global-set-key (kbd "C-x g") 'magit-status-quick).
+@end lisp
+
+If you do that and then for once want to redisplay the buffer and
+also immediately refresh it, then type @code{C-x g} followed by @code{g}.
+
+A possible alternative command is @code{magit-display-repository-buffer}.
+It supports displaying any existing Magit buffer that belongs to the
+current repository; not just the status buffer.
+@end deffn
+
 @cindex ido-enter-magit-status
 @deffn Command ido-enter-magit-status
 
@@ -9450,6 +9480,26 @@ displayed in the current buffer, then show it in Dired 
instead.
 @node Common Commands
 @section Common Commands
 
+@cindex magit-switch-to-repository-buffer
+@deffn Command magit-switch-to-repository-buffer
+@end deffn
+@cindex magit-switch-to-repository-buffer-other-window
+@deffn Command magit-switch-to-repository-buffer-other-window
+@end deffn
+@cindex magit-switch-to-repository-buffer-other-frame
+@deffn Command magit-switch-to-repository-buffer-other-frame
+@end deffn
+@cindex magit-display-repository-buffer
+@deffn Command magit-display-repository-buffer
+
+These commands read any existing Magit buffer that belongs to the
+current repository from the user and then switch to the selected
+buffer (without refreshing it).
+
+The last variant uses @code{magit-display-buffer} to do so and thus
+respects @code{magit-display-buffer-function}.
+@end deffn
+
 These are some of the commands that can be used in all buffers whose
 major-modes derive from @code{magit-mode}.  There are other common commands
 beside the ones below, but these didn't fit well anywhere else.
diff --git a/lisp/magit-extras.el b/lisp/magit-extras.el
index a7f1cbe..d621298 100644
--- a/lisp/magit-extras.el
+++ b/lisp/magit-extras.el
@@ -753,6 +753,51 @@ abbreviated revision to the `kill-ring' and the
         (push (list rev default-directory) magit-revision-stack)
         (kill-new (message "%s" rev))))))
 
+;;; Buffer Switching
+
+(defun magit-display-repository-buffer (buffer)
+  "Display a Magit buffer belonging to the current Git repository.
+The buffer is displayed using `magit-display-buffer', which see."
+  (interactive (list (magit--read-repository-buffer
+                      "Display magit buffer: ")))
+  (magit-display-buffer buffer))
+
+(defun magit-switch-to-repository-buffer (buffer)
+  "Switch to a Magit buffer belonging to the current Git repository."
+  (interactive (list (magit--read-repository-buffer
+                      "Switch to magit buffer: ")))
+  (switch-to-buffer buffer))
+
+(defun magit-switch-to-repository-buffer-other-window (buffer)
+  "Switch to a Magit buffer belonging to the current Git repository."
+  (interactive (list (magit--read-repository-buffer
+                      "Switch to magit buffer in another window: ")))
+  (switch-to-buffer-other-window buffer))
+
+(defun magit-switch-to-repository-buffer-other-frame (buffer)
+  "Switch to a Magit buffer belonging to the current Git repository."
+  (interactive (list (magit--read-repository-buffer
+                      "Switch to magit buffer in another frame: ")))
+  (switch-to-buffer-other-frame buffer))
+
+(defun magit--read-repository-buffer (prompt)
+  (if-let ((topdir (magit-rev-parse-safe "--show-toplevel")))
+      (read-buffer
+       prompt (magit-get-mode-buffer 'magit-status-mode) t
+       (pcase-lambda (`(,_ . ,buf))
+         (and buf
+              (with-current-buffer buf
+                (and (or (derived-mode-p 'magit-mode
+                                         'magit-repolist-mode
+                                         'magit-submodule-list-mode
+                                         'git-rebase-mode)
+                         (and buffer-file-name
+                              (string-match-p git-commit-filename-regexp
+                                              buffer-file-name)))
+                     (equal (magit-rev-parse-safe "--show-toplevel")
+                            topdir))))))
+    (user-error "Not inside a Git repository")))
+
 ;;; Miscellaneous
 
 ;;;###autoload
diff --git a/lisp/magit-mode.el b/lisp/magit-mode.el
index bf8f21c..2e967e9 100644
--- a/lisp/magit-mode.el
+++ b/lisp/magit-mode.el
@@ -369,6 +369,8 @@ recommended value."
     (define-key map "G" 'magit-refresh-all)
     (define-key map "h" 'magit-dispatch)
     (define-key map "?" 'magit-dispatch)
+    (define-key map "j" 'magit-status-quick)
+    (define-key map "J" 'magit-display-repository-buffer)
     (define-key map "l" 'magit-log)
     (define-key map "L" 'magit-log-refresh)
     (define-key map "m" 'magit-merge)
diff --git a/lisp/magit-status.el b/lisp/magit-status.el
index 3b20d61..46bc224 100644
--- a/lisp/magit-status.el
+++ b/lisp/magit-status.el
@@ -309,6 +309,29 @@ also contains other useful hints.")
 
 (put 'magit-status-here 'interactive-only 'magit-status-setup-buffer)
 
+(defun magit-status-quick ()
+  "Show the status of the current Git repository, maybe without refreshing.
+
+If the status buffer of the current Git repository exists but
+isn't being displayed in the selected frame, then display it
+without refreshing it.
+
+If the status buffer is being displayed in the selected frame,
+then also refresh it.
+
+Prefix arguments have the same meaning as for `magit-status',
+and additionally cause the buffer to be refresh.
+
+To use this function instead of `magit-status', add this to your
+init file: (global-set-key (kbd \"C-x g\") 'magit-status-quick)."
+  (interactive)
+  (if-let ((buffer
+            (and (not current-prefix-arg)
+                 (not (magit-get-mode-buffer 'magit-status-mode nil 'selected))
+                 (magit-get-mode-buffer 'magit-status-mode))))
+      (magit-display-buffer buffer)
+    (call-interactively #'magit-status)))
+
 (defvar magit--remotes-using-recent-git nil)
 
 (defun magit--tramp-asserts (directory)
diff --git a/lisp/magit.el b/lisp/magit.el
index 13a5a14..50e196b 100644
--- a/lisp/magit.el
+++ b/lisp/magit.el
@@ -308,6 +308,9 @@ Also see info node `(magit)Commands for Buffers Visiting 
Files'."
    [("f" "Fetch"          magit-fetch)
     ("F" "Pull"           magit-pull)
     ("I" "Init"           magit-init)
+    ("j" "Jump to section"magit-status-jump  :if-mode     magit-status-mode)
+    ("j" "Display status" magit-status-quick :if-not-mode magit-status-mode)
+    ("J" "Display buffer" magit-display-repository-buffer)
     ("l" "Log"            magit-log)
     ("L" "Log (change)"   magit-log-refresh)
     ("m" "Merge"          magit-merge)