Tabpage

Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.

Editing with windows in multiple tab pages.tabpage

The commands which have been added to use multiple tab pages are explainedhere. Additionally, there are explanations for commands that work differentlywhen used in combination with more than one tab page.

1. Introductiontab-page-intro

A tab page holds one or more windows. You can easily switch between tabpages, so that you have several collections of windows to work on differentthings.

Usually you will see a list of labels at the top of the Vim window, one foreach tab page. With the mouse you can click on the label to jump to that tabpage. There are other ways to move between tab pages, see below.

Most commands work only in the current tab page. That includes theCTRL-Wcommands,:windo,:all and:ball (when not using the:tab modifier).The commands that are aware of other tab pages than the current one arementioned below.

Tab pages are also a nice way to edit a buffer temporarily without changingthe current window layout. Open a new tab page, do whatever you want to doand close the tab page.

tab-IDtabidtabpageidEach tab page has a unique identifier called the tab ID. This identifier willnot change within a Vim session -- even when rearranging tabs.nvim_get_current_tabpage() returns the tab ID andnvim_list_tabpages()lists tab IDs in the order they're displayed. Additionally, the tabs arenumbered from left to right starting at 1: this is the tab number returned bytabpagenr(). However, the tab number may change when tabs are opened,closed, or rearranged.nvim_tabpage_get_number() converts a tab ID to a tabnumber.

2. Commandstab-page-commands

OPENING A NEW TAB PAGE:

When starting Vim "vim -p filename ..." opens each file argument in a separatetab page (up to'tabpagemax'). See-p

A double click with the mouse in the non-GUI tab pages line opens a new, emptytab page. It is placed left of the position of the click. The first clickmay select another tab page first, causing an extra screen update.

This also works in a few GUI versions, esp. Win32. But only when clickingright of the labels.

In the GUI tab pages line you can use the right mouse button to open menu.tabline-menu.

For the related autocommands seetabnew-autocmd.

:[count]tabe[dit]:tabe:tabedit:tabnew:[count]tabnewOpen a new tab page with an empty window, after the currenttab page. If [count] is given the new tab page appears afterthe tabpage [count] otherwise the new tab page will appearafter the current one.

:tabnew     " opens tabpage after the current one:.tabnew    " as above:+tabnew    " opens tabpage after the next tab page            " note: it is one further than :tabnew:-tabnew    " opens tabpage before the current:0tabnew    " opens tabpage before the first one:$tabnew    " opens tabpage after the last one

:[count]tabe[dit] [++opt] [+cmd]{file}:[count]tabnew [++opt] [+cmd]{file}Open a new tab page and edit{file}, like with:edit.For [count] see:tabnew above.

:[count]tabf[ind] [++opt] [+cmd]{file}:tabf:tabfindOpen a new tab page and edit{file} in'path', like with:find. For [count] see:tabnew above.

:[count]tab{cmd}:tab
Execute{cmd} and when it opens a new window open a new tabpage instead. Doesn't work for:diffsplit,:diffpatch,:execute and:normal.If [count] is given the new tab page appears after the tabpage [count] otherwise the new tab page will appear after thecurrent one.Examples:

:tab split    " opens current buffer in new tab page:tab help gt    " opens tab page with help for "gt":.tab help gt   " as above:+tab help    " opens tab page with help after the next                " tab page:-tab help    " opens tab page with help before the                " current one:0tab help    " opens tab page with help before the                " first one:$tab help    " opens tab page with help after the last                " one

CTRL-W gfOpen a new tab page and edit the file name under the cursor.SeeCTRL-W_gf.

CTRL-W gFOpen a new tab page and edit the file name under the cursorand jump to the line number following the file name.SeeCTRL-W_gF.

CLOSING A TAB PAGE:

Closing the last window of a tab page closes the tab page too, unless there isonly one tab page.

Using the mouse: If the tab page line is displayed you can click in the "X" atthe top right to close the current tab page. A custom'tabline' may showsomething else.

:tabc:tabclose:tabc[lose][!]Close current tab page.This command fails when:

There is only one tab page on the screen.E784

When'hidden' is not set, [!] is not used, a buffer has changes, and there is no other window on this buffer.Changes to the buffer are not written and won't get lost, sothis is a "safe" command.

:tabclose   " close the current tab page

:{count}tabc[lose][!]:tabc[lose][!]{count}Close tab page{count}. Fails in the same way as:tabcloseabove.

:-tabclose    " close the previous tab page:+tabclose    " close the next tab page:1tabclose    " close the first tab page:$tabclose    " close the last tab page:tabclose -2    " close the 2nd previous tab page:tabclose +    " close the next tab page:tabclose 3    " close the third tab page:tabclose $    " close the last tab page:tabclose #     " close the last accessed tab page

When a tab page is closed the next tab page will become the current one. Thisbehaviour can be customized using the'tabclose' option.

:tabo:tabonly:tabo[nly][!]Close all other tab pages.When the'hidden' option is set, all buffers in closed windowsbecome hidden.When'hidden' is not set, and the'autowrite' option is set,modified buffers are written. Otherwise, windows that havebuffers that are modified are not removed, unless the [!] isgiven, then they become hidden. But modified buffers arenever abandoned, so changes cannot get lost.

:tabonly " close all tab pages except the current one

:tabo[nly][!]{count}Close all tab pages except{count} one.

:.tabonly    " as above:-tabonly    " close all tab pages except the previous                " one:+tabonly    " close all tab pages except the next one:1tabonly    " close all tab pages except the first one:$tabonly    " close all tab pages except the last one:tabonly -    " close all tab pages except the previous                " one:tabonly +2     " close all tab pages except the two next                " one:tabonly 1    " close all tab pages except the first one:tabonly $    " close all tab pages except the last one:tabonly #    " close all tab pages except the last                " accessed one

SWITCHING TO ANOTHER TAB PAGE:

Using the mouse: If the tab page line is displayed you can click in a tab pagelabel to switch to that tab page. Click where there is no label to go to thenext tab page.'tabline'

:tabn[ext]:tabn:tabnextgt<C-PageDown>CTRL-<PageDown><C-PageDown>gti_CTRL-<PageDown>i_<C-PageDown>Go to the next tab page. Wraps around from the last to thefirst one.

:{count}tabn[ext]:tabn[ext]{count}Go to tab page{count}. The first tab page has number one.

:-tabnext" go to the previous tab page:+tabnext" go to the next tab page:+2tabnext" go to the two next tab page:1tabnext" go to the first tab page:$tabnext" go to the last tab page:tabnext $" as above:tabnext #" go to the last accessed tab page:tabnext -" go to the previous tab page:tabnext -1" as above:tabnext +" go to the next tab page:tabnext +1" as above

{count}<C-PageDown>{count}gtGo to tab page{count}. The first tab page has number one.

:tabp[revious]:tabp:tabpreviousgT:tabN:tabN[ext]:tabNextCTRL-<PageUp><C-PageUp><C-PageUp>i_CTRL-<PageUp>i_<C-PageUp>gTGo to the previous tab page. Wraps around from the first oneto the last one.

:tabp[revious]{count}:tabN[ext]{count}{count}<C-PageUp>{count}gTGo{count} tab pages back. Wraps around from the first oneto the last one. Note that the use of{count} is differentfrom:tabnext, where it is used as the tab page number.

:tabr[ewind]:tabfir:tabfirst:tabr:tabrewind:tabfir[st]Go to the first tab page.

:tabl:tablast:tabl[ast]Go to the last tab page.

<C-Tab>CTRL-<Tab><C-Tab>g<Tab>g<Tab>CTRL-W_g<Tab>CTRL-W g<Tab>Go to the last accessed tab page.

Other commands::tabs
:tabsList the tab pages and the windows they contain.Shows a ">" for the current window.Shows a "+" for modified buffers.For example:

Tab page 1

+ tabpage.txt

ex_docmd.c

Tab page 2

> main.c

REORDERING TAB PAGES:

:tabm[ove] [N]:tabm:tabmove:[N]tabm[ove]Move the current tab page to after tab page N. Use zero tomake the current tab page the first one. N is counted beforethe move, thus if the second tab page is the current one,:tabmove 1 and:tabmove 2 have no effect.Without N the tab page is made the last one.

:.tabmove" do nothing:-tabmove" move the tab page to the left:+tabmove" move the tab page to the right:0tabmove" move the tab page to the first:tabmove 0" as above:tabmove" move the tab page to the last:$tabmove" as above:tabmove $" as above:tabmove #" move the tab page after the last accessed            " tab page

:tabm[ove] +[N]:tabm[ove] -[N]Move the current tab page N places to the right (with +) or tothe left (with -).

:tabmove -" move the tab page to the left:tabmove -1" as above:tabmove +" move the tab page to the right:tabmove +1" as above

Note that although it is possible to move a tab page behind the N-th one byusing :Ntabmove. And move it by N places by using :+Ntabmove. Forclarification what +N means in this context see[range].

LOOPING OVER TAB PAGES:

:tabd:tabdo:[range]tabd[o]{cmd}Execute{cmd} in each tab page or, if [range] is given, onlyin tabpages which tab page number is in the [range]. It workslike doing this:

:tabfirst:{cmd}:tabnext:{cmd}etc.

This only operates in the current window of each tab page.When an error is detected on one tab page, further tab pageswill not be visited.The last tab page (or where an error occurred) becomes thecurrent tab page.{cmd} can contain '|' to concatenate several commands.{cmd} must not open or close tab pages or reorder them.Also see:windo,:argdo,:bufdo,:cdo,:ldo,:cfdoand:lfdo.

3. Other itemstab-page-other

tabline-menu
The GUI tab pages line has a popup menu. It is accessed with a right click.The entries are:CloseClose the tab page under the mouse pointer. Thecurrent one if there is no label under the mousepointer.New TabOpen a tab page, editing an empty buffer. It appearsto the left of the mouse pointer.Open Tab...Like "New Tab" and additionally use a file selector toselect a file to edit.

Diff mode works per tab page. You can see the diffs between several fileswithin one tab page. Other tab pages can show differences between otherfiles.

Variables local to a tab page start with "t:".tabpage-variable

Currently there is only one option local to a tab page:'cmdheight'.

tabnew-autocmd
The TabLeave and TabEnter autocommand events can be used to do something whenswitching from one tab page to another. The exact order depends on what youare doing. When creating a new tab page this works as if you create a newwindow on the same buffer and then edit another buffer. Thus ":tabnew"triggers:WinLeaveleave current windowTabLeaveleave current tab pageWinEnterenter window in new tab pageTabEnterenter new tab pageBufLeaveleave current bufferBufEnterenter new empty buffer

When switching to another tab page the order is:BufLeaveWinLeaveTabLeaveWinEnterTabEnterBufEnter

When entering a new tab page (:tabnew), TabNew is triggered before TabEnterand after WinEnter.

4. Setting'tabline'setting-tabline

The'tabline' option specifies what the line with tab pages labels looks like.It is only used when there is no GUI tab line.

You can use the'showtabline' option to specify when you want the line withtab page labels to appear: never, when there is more than one tab page oralways.

The highlighting of the tab pages line is set with the groups TabLineTabLineSel and TabLineFill.hl-TabLine hl-TabLineSel hl-TabLineFill

A "+" will be shown for a tab page that has a modified window. The number ofwindows in a tabpage is also shown. Thus "3+" means three windows and one ofthem has a modified buffer.

The'tabline' option allows you to define your preferred way to tab pageslabels. This isn't easy, thus an example will be given here.

For basics see the'statusline' option. The same items can be used in the'tabline' option. Additionally, thetabpagebuflist(),tabpagenr() andtabpagewinnr() functions are useful.

Since the number of tab labels will vary, you need to use an expression forthe whole option. Something like:

:set tabline=%!MyTabLine()

Then define the MyTabLine() function to list all the tab pages labels. Aconvenient method is to split it in two parts: First go over all the tabpages and define labels for them. Then get the label for each tab page.

function MyTabLine()  let s = ''  for i in range(tabpagenr('$'))    " select the highlighting    if i + 1 == tabpagenr()      let s ..= '%#TabLineSel#'    else      let s ..= '%#TabLine#'    endif    " set the tab page number (for mouse clicks)    let s ..= '%' .. (i + 1) .. 'T'    " the label is made by MyTabLabel()    let s ..= ' %{MyTabLabel(' .. (i + 1) .. ')} '  endfor  " after the last tab page fill with TabLineFill and reset tab page nr  let s ..= '%#TabLineFill#%T'  " right-align the label to close the current tab page  if tabpagenr('$') > 1    let s ..= '%=%#TabLine#%999Xclose'  endif  return sendfunction

Now the MyTabLabel() function is called for each tab page to get its label.

function MyTabLabel(n)  let buflist = tabpagebuflist(a:n)  let winnr = tabpagewinnr(a:n)  return bufname(buflist[winnr - 1])endfunction

This is just a simplistic example that results in a tab pages line thatresembles the default, but without adding a + for a modified buffer ortruncating the names. You will want to reduce the width of labels in aclever way when there is not enough room. Check the'columns' option for thespace available.

5. Setting'guitablabel'setting-guitablabel

When the GUI tab pages line is displayed,'guitablabel' can be used tospecify the label to display for each tab page. Unlike'tabline', whichspecifies the whole tab pages line at once,'guitablabel' is used for eachlabel separately.

'guitabtooltip' is very similar and is used for the tooltip of the same label.This only appears when the mouse pointer hovers over the label, thus itusually is longer. Only supported on some systems though.

See the'statusline' option for the format of the value.

The "%N" item can be used for the current tab page number. Thev:lnumvariable is also set to this number when the option is evaluated.The items that use a file name refer to the current window of the tab page.

Note that syntax highlighting is not used for the option. The %T and %Xitems are also ignored.

A simple example that puts the tab page number and the buffer name in thelabel:

:set guitablabel=%N\ %f

An example that resembles the default'guitablabel': Show the number ofwindows in the tab page and a '+' if there is a modified buffer:

function GuiTabLabel()  let label = ''  let bufnrlist = tabpagebuflist(v:lnum)  " Add '+' if one of the buffers in the tab page is modified  for bufnr in bufnrlist    if getbufvar(bufnr, "&modified")      let label = '+'      break    endif  endfor  " Append the number of windows in the tab page if more than one  let wincount = tabpagewinnr(v:lnum, '$')  if wincount > 1    let label ..= wincount  endif  if label != ''    let label ..= ' '  endif  " Append the buffer name  return label .. bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])endfunctionset guitablabel=%{GuiTabLabel()}

Note that the function must be defined before setting the option, otherwiseyou get an error message for the function not being known.

If you want to fall back to the default label, return an empty string.

If you want to show something specific for a tab page, you might want to use atab page local variable.t:var