Core Library0.xAPI Reference

Choose documentation 3

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

method libtmux-go latest

Session.NewWindow

NewWindow creates a winlink in the receiver session. Attach selects it as that session's current window; it is not a guarantee about clients attached to other sessions. The returned Window is freshly materialized in the receiver's exact session context, including when its stable WindowID is linked elsewhere.

Source and package
Qualified name
tmux.Session.NewWindow
Package
tmux
Declared in
Session
Distribution
github.com/libtmux/libtmux-go/tmux
Source
tmux/window_lifecycle.go
Other languages
Perlmethod Erlang PowerShell Julia Elixir Haskell Common Lisp PythonRubyLuaTypeScriptRustJavaC#C++SwiftKotlinScalaOCaml F# Clojure

Description#

SelectExisting no-output recovery is available only when Index is nil. It expands Name with tmux's version-specific rules and requires exactly one matching window name in the receiver session. An explicit Index has no such recovery. If tmux reports a WindowID before a transport or refresh failure, the partial result contains that ID and the receiver SessionID with Index -1. Other failures return zero; creation is not rolled back.

Examples#

Add a logs window to an existing session without selecting it. NewWindow returns the newly materialized window and its initial pane relation; the session record from NewSession still carries no window relations. Use Go 1.26 or newer and tmux 3.3a or newer on a Unix system, with tmux and cat on PATH. In a new directory, create a module and add the library from the Go module proxy:

Terminal window
$ go mod init example.com/libtmux-api && \
go get github.com/libtmux/libtmux-go@latest

Save this complete example as example_test.go. It creates a private temporary socket and stops its server before removing the directory. Cleanup failure fails the example and retains the socket directory. View source

package tmux_test
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"time"
"github.com/libtmux/libtmux-go/tmux"
)
// Add a logs window to an existing session without selecting it. NewWindow
// returns the newly materialized window and its initial pane relation;
// the session record from NewSession still carries no window relations.
func ExampleSession_NewWindow_complete() {
run := func() (runErr error) {
directory, err := os.MkdirTemp("", "libtmux-go-api-")
if err != nil {
return fmt.Errorf("create socket directory: %w", err)
}
server, err := tmux.NewServer(tmux.ServerOptions{
SocketPath: filepath.Join(directory, "tmux.sock"),
ConfigFile: "/dev/null",
})
if err != nil {
return errors.Join(err, os.RemoveAll(directory))
}
defer func() {
// Cleanup has its own deadline because the operation may have timed out.
cleanup, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := server.Kill(cleanup); err != nil && !errors.Is(err, tmux.ErrNoServer) {
runErr = errors.Join(runErr, fmt.Errorf("stop server at %s: %w", directory, err))
return
}
runErr = errors.Join(runErr, os.RemoveAll(directory))
}()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
session, err := server.NewSession(ctx, tmux.NewSessionRequest{
Name: "work", WindowName: "editor", Command: "cat", Width: 100, Height: 30,
})
if err != nil {
return fmt.Errorf("create session: %w", err)
}
name := "logs"
window, err := session.NewWindow(ctx, tmux.NewWindowRequest{
Name: &name, Command: "cat",
})
if err != nil {
return fmt.Errorf("create logs window: %w", err)
}
windowName, ok := window.Name()
if !ok {
return errors.New("created window has no name")
}
panes, relations := window.Panes()
fmt.Println("window:", windowName)
fmt.Println("initial panes:", len(panes), "captured:", relations)
windows, err := session.SearchWindows(ctx, nil)
if err != nil {
return fmt.Errorf("list current windows: %w", err)
}
fmt.Println("live windows:", len(windows))
current, err := session.ResolveActiveWindow(ctx)
if err != nil {
return fmt.Errorf("resolve current window: %w", err)
}
currentName, ok := current.Name()
if !ok {
return errors.New("current window has no name")
}
fmt.Println("current window:", currentName)
return nil
}
if err := run(); err != nil {
panic(err)
}
// Output:
// window: logs
// initial panes: 1 captured: true
// live windows: 2
// current window: editor
}

Run the saved file. Go checks the Output comment and fails on different output or an operation or cleanup error:

Terminal window
$ go test -count=1 -v example_test.go

tmux command#

The tmux commands behind NewWindow.

tmux C API#

The C declarations in tmux that implement these commands.

Guides#

Pages that discuss NewWindow.

In other ports#

Create a window

Equivalents of Create a window in other languages
Language Equivalent
Python libtmux.Session.new_window
Ruby LibTmux::Session#new_window
Lua libtmux.Session:new_window
Erlang tmux_window:create/2
Haskell No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript session.Session.newWindow
Rust session.Session.new_window
Java io.github.libtmux.Session.newWindow
Clojure libtmux.core/new-window!
Kotlin io.github.libtmux.kotlin.Session.newWindow
Scala io.github.libtmux.scaladsl.Session.newWindow
C# LibTmux.Session.CreateWindowAsync
C++ libtmux::Session::new_window
Swift Server.newWindow(in:named:startDirectory:at:environment:shell:)
OCaml Libtmux_unix.Client.create_window
Perl LibTmux::Server::new_window Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes.

No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.

Esc

Type to search.

Reference previewOpen reference