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
- func (s Session) NewWindow( ctx context
.Context , request NewWindow , ) (Window, error)Request -
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
tmuxandcatonPATH. 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@latestSave 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 sourcepackage tmux_testimport ("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- Parameters
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
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| Erlang | tmux |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| TypeScript | session |
| Rust | session |
| Java | io |
| Clojure | libtmux |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| C++ | libtmux:: |
| Swift | Server |
| OCaml | Libtmux |
| Perl | Lib 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#.