vim-patch:8.2.1967: the session file does not restore the alternate file

Problem:    The session file does not restore the alternate file.
Solution:   Add ":balt".  Works like ":badd" and also sets the buffer as the
            alternate file.  Use it in the session file. (closes vim/vim#7269,
            closes vim/vim#6714)
59d8e56e04

Include minimal test_buffer.vim from patch 8.2.0243 for Test_balt().
Add entry for :balt to runtime/doc/index.txt from vim/vim#7819.

runtime/doc/index.txt

@@ -1144,6 +1144,7 @@ tag		command		action ~
 |:bNext|	:bN[ext]	go to previous buffer in the buffer list
 |:ball|		:ba[ll]		open a window for each buffer in the buffer list
 |:badd|		:bad[d]		add buffer to the buffer list
+|:balt|		:balt		like ":badd" but also set the alternate file
 |:bdelete|	:bd[elete]	remove a buffer from the buffer list
 |:behave|	:be[have]	set mouse and selection behavior
 |:belowright|	:bel[owright]	make split window appear right or below

runtime/doc/windows.txt

@@ -1039,6 +1039,11 @@ list of buffers. |unlisted-buffer|
 		line when the buffer is first entered.  Note that other
 		commands after the + will be ignored.
 
+						 *:balt*
+:balt [+lnum] {fname}
+		Like `:badd` and also set the alternate file for the current
+		window to {fname}.
+
 :[N]bd[elete][!]			*:bd* *:bdel* *:bdelete* *E516*
 :bd[elete][!] [N]
 		Unload buffer [N] (default: current buffer) and delete it from

src/nvim/ex_cmds.c

@@ -2181,6 +2181,8 @@ theend:
 ///                 ECMD_OLDBUF: use existing buffer if it exists
 ///                 ECMD_FORCEIT: ! used for Ex command
 ///                 ECMD_ADDBUF: don't edit, just add to buffer list
+///                 ECMD_ALTBUF: like ECMD_ADDBUF and also set the alternate
+///                 file
 /// @param oldwin   Should be "curwin" when editing a new buffer in the current
 ///                 window, NULL when splitting the window first.  When not NULL
 ///                 info of the previous buffer for "oldwin" is stored.
@@ -2237,8 +2239,10 @@ int do_ecmd(
       path_fix_case(sfname);             // set correct case for sfname
 #endif
 
-    if ((flags & ECMD_ADDBUF) && (ffname == NULL || *ffname == NUL))
+    if ((flags & (ECMD_ADDBUF | ECMD_ALTBUF))
+        && (ffname == NULL || *ffname == NUL)) {
       goto theend;
+    }
 
     if (ffname == NULL)
       other_file = TRUE;
@@ -2268,15 +2272,16 @@ int do_ecmd(
   // If the file was changed we may not be allowed to abandon it:
   // - if we are going to re-edit the same file
   // - or if we are the only window on this file and if ECMD_HIDE is FALSE
-  if (  ((!other_file && !(flags & ECMD_OLDBUF))
-         || (curbuf->b_nwindows == 1
-             && !(flags & (ECMD_HIDE | ECMD_ADDBUF))))
-        && check_changed(curbuf, (p_awa ? CCGD_AW : 0)
-            | (other_file ? 0 : CCGD_MULTWIN)
-            | ((flags & ECMD_FORCEIT) ? CCGD_FORCEIT : 0)
-            | (eap == NULL ? 0 : CCGD_EXCMD))) {
-    if (fnum == 0 && other_file && ffname != NULL)
+  if (((!other_file && !(flags & ECMD_OLDBUF))
+       || (curbuf->b_nwindows == 1
+           && !(flags & (ECMD_HIDE | ECMD_ADDBUF | ECMD_ALTBUF))))
+      && check_changed(curbuf, (p_awa ? CCGD_AW : 0)
+                       | (other_file ? 0 : CCGD_MULTWIN)
+                       | ((flags & ECMD_FORCEIT) ? CCGD_FORCEIT : 0)
+                       | (eap == NULL ? 0 : CCGD_EXCMD))) {
+    if (fnum == 0 && other_file && ffname != NULL) {
       (void)setaltfname(ffname, sfname, newlnum < 0 ? 0 : newlnum);
+    }
     goto theend;
   }
 
@@ -2306,17 +2311,19 @@ int do_ecmd(
    * Otherwise we re-use the current buffer.
    */
   if (other_file) {
-    if (!(flags & ECMD_ADDBUF)) {
-      if (!cmdmod.keepalt)
+    if (!(flags & (ECMD_ADDBUF | ECMD_ALTBUF))) {
+      if (!cmdmod.keepalt) {
         curwin->w_alt_fnum = curbuf->b_fnum;
-      if (oldwin != NULL)
+      }
+      if (oldwin != NULL) {
         buflist_altfpos(oldwin);
+      }
     }
 
     if (fnum) {
       buf = buflist_findnr(fnum);
     } else {
-      if (flags & ECMD_ADDBUF) {
+      if (flags & (ECMD_ADDBUF | ECMD_ALTBUF)) {
         linenr_T tlnum = 1L;
 
         if (command != NULL) {
@@ -2324,7 +2331,11 @@ int do_ecmd(
           if (tlnum <= 0)
             tlnum = 1L;
         }
-        (void)buflist_new(ffname, sfname, tlnum, BLN_LISTED);
+        const buf_T *const newbuf
+            = buflist_new(ffname, sfname, tlnum, BLN_LISTED);
+        if (newbuf != NULL && (flags & ECMD_ALTBUF)) {
+          curwin->w_alt_fnum = newbuf->b_fnum;
+        }
         goto theend;
       }
       buf = buflist_new(ffname, sfname, 0L,
@@ -2470,8 +2481,7 @@ int do_ecmd(
     curwin->w_pcmark.lnum = 1;
     curwin->w_pcmark.col = 0;
   } else {  // !other_file
-    if ((flags & ECMD_ADDBUF)
-        || check_fname() == FAIL) {
+    if ((flags & (ECMD_ADDBUF | ECMD_ALTBUF)) || check_fname() == FAIL) {
       goto theend;
     }
     oldbuf = (flags & ECMD_OLDBUF);

src/nvim/ex_cmds.h

@@ -16,7 +16,7 @@
 #define ECMD_OLDBUF          0x04    // use existing buffer if it exists
 #define ECMD_FORCEIT         0x08    // ! used in Ex command
 #define ECMD_ADDBUF          0x10    // don't edit, just add to buffer list
-
+#define ECMD_ALTBUF         0x20  // like ECMD_ADDBUF and set the alternate file
 
 /* for lnum argument in do_ecmd() */
 #define ECMD_LASTL      (linenr_T)0     /* use last position in loaded file */

src/nvim/ex_cmds.lua

@@ -175,6 +175,12 @@ module.cmds = {
     addr_type='ADDR_NONE',
     func='ex_edit',
   },
+  {
+    command='balt',
+    flags=bit.bor(NEEDARG, FILE1, CMDARG, TRLBAR, CMDWIN),
+    addr_type='ADDR_NONE',
+    func='ex_edit',
+  },
   {
     command='bdelete',
     flags=bit.bor(BANG, RANGE, BUFNAME, COUNT, EXTRA, TRLBAR),

src/nvim/ex_docmd.c

@@ -7271,9 +7271,7 @@ static void ex_find(exarg_T *eap)
   }
 }
 
-/*
- * ":edit", ":badd", ":visual".
- */
+/// ":edit", ":badd", ":balt", ":visual".
 static void ex_edit(exarg_T *eap)
 {
   do_exedit(eap, NULL);
@@ -7355,6 +7353,7 @@ do_exedit(
                 // After a split we can use an existing buffer.
                 + (old_curwin != NULL ? ECMD_OLDBUF : 0)
                 + (eap->cmdidx == CMD_badd ? ECMD_ADDBUF : 0)
+                + (eap->cmdidx == CMD_balt ? ECMD_ALTBUF : 0)
                 , old_curwin == NULL ? curwin : NULL) == FAIL) {
       // Editing the file failed.  If the window was split, close it.
       if (old_curwin != NULL) {
@@ -8725,7 +8724,7 @@ ssize_t find_cmdline_var(const char_u *src, size_t *usedlen)
  * Evaluate cmdline variables.
  *
  * change '%'	    to curbuf->b_ffname
- *	  '#'	    to curwin->w_altfile
+ *	  '#'	    to curwin->w_alt_fnum
  *	  '<cword>' to word under the cursor
  *	  '<cWORD>' to WORD under the cursor
  *	  '<cexpr>' to C-expression under the cursor

src/nvim/ex_session.c

@@ -384,6 +384,17 @@ static int put_view(
     xfree(fname_esc);
   }
 
+  if (wp->w_alt_fnum) {
+    buf_T *const alt = buflist_findnr(wp->w_alt_fnum);
+
+    // Set the alternate file.
+    if (alt != NULL && alt->b_fname != NULL && *alt->b_fname != NUL
+        && (fputs("balt ", fd) < 0
+            || ses_fname(fd, alt, flagp, true) == FAIL)) {
+      return FAIL;
+    }
+  }
+
   //
   // Local mappings and abbreviations.
   //

src/nvim/testdir/test_buffer.vim

@@ -0,0 +1,10 @@
+" Tests for Vim buffer
+
+func Test_balt()
+  new SomeNewBuffer
+  balt +3 OtherBuffer
+  e #
+  call assert_equal('OtherBuffer', bufname())
+endfunc
+
+" vim: shiftwidth=2 sts=2 expandtab