Add several commands for switching to existing Magit buffers

Closes #4259.

3 files changed, 102 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.