.github/workflows | ||
testdata | ||
travis | ||
barconfig.go | ||
bindingmodes.go | ||
byteorder_test.go | ||
byteorder.go | ||
close_test.go | ||
command.go | ||
common_test.go | ||
config.go | ||
doc.go | ||
example_test.go | ||
getpid.go | ||
go.mod | ||
go.sum | ||
golden_test.go | ||
LICENSE | ||
marks.go | ||
outputs.go | ||
README.md | ||
restart_test.go | ||
socket.go | ||
subscribe_test.go | ||
subscribe.go | ||
sync_test.go | ||
sync.go | ||
tick.go | ||
tree_utils_test.go | ||
tree_utils.go | ||
tree.go | ||
validpid.go | ||
version.go | ||
workspaces.go |
Package i3 provides a convenient interface to the i3 window manager via its IPC interface.
See its documentation for more details.
Start using it
In module mode, use import path
go.i3wm.org/i3/v4
.
In non-module mode, use import path go.i3wm.org/i3
.
Advantages over other i3 IPC packages
Here comes a grab bag of features to which we paid attention. At the time of writing, most other i3 IPC packages lack at least a good number of these features:
-
Retries are transparently handled: programs using this package will recover automatically from in-place i3 restarts. Additionally, programs can be started from xsession or user sessions before i3 is even running.
-
Version checks are transparently handled: if your program uses features which are not supported by the running i3 version, helpful error messages will be returned at run time.
-
Comprehensive: the entire documented IPC interface of the latest stable i3 version is covered by this package. Tagged releases match i3’s major and minor version.
-
Consistent and familiar: once familiar with the i3 IPC protocol’s features, you should have no trouble matching the documentation to API and vice-versa.
-
Good test coverage (hard to display in a badge, as our multi-process setup breaks
go test
’s-coverprofile
flag). -
Implemented in pure Go, without resorting to the
unsafe
package. -
Works on little and big endian architectures.
Scope
i3’s entire documented IPC interface is available in this package.
In addition, helper functions which are useful for a broad range of programs (and only those!) are provided, e.g. Node’s FindChild and FindFocused.
Packages which introduce higher-level abstractions should feel free to use this package as a building block.
Assumptions
- The
i3(1)
binary must be in$PATH
so that the IPC socket path can be retrieved. - For transparent version checks to work, the running i3 version must be ≥ 4.3 (released 2012-09-19).
Testing
Be sure to include the target i3 version (the most recent stable release) in
$PATH
and use go test
as usual:
PATH=~/i3/build/i3:$PATH go test -v go.i3wm.org/i3