Package i3 provides a convenient interface to the i3 window manager
Clone or download
Latest commit e2468ef Nov 5, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
testdata Initial commit Sep 29, 2017
travis tests: update to i3 v4.16 Nov 5, 2018
.travis.yml travis: switch to go 1.11 Nov 5, 2018
LICENSE Initial commit Sep 29, 2017
README.md README: add godoc badge Sep 29, 2017
barconfig.go Initial commit Sep 29, 2017
bindingmodes.go Initial commit Sep 29, 2017
byteorder.go Initial commit Sep 29, 2017
byteorder_test.go Initial commit Sep 29, 2017
command.go Initial commit Sep 29, 2017
common_test.go Initial commit Sep 29, 2017
config.go Initial commit Sep 29, 2017
doc.go Initial commit Sep 29, 2017
example_test.go Initial commit Sep 29, 2017
getpid.go Initial commit Sep 29, 2017
go.mod declare a go module Nov 5, 2018
go.sum declare a go module Nov 5, 2018
golden_test.go tests: update to i3 v4.16 Nov 5, 2018
marks.go Initial commit Sep 29, 2017
outputs.go Initial commit Sep 29, 2017
restart_test.go reduce shared memory logfile size from 25M to 5M May 5, 2018
socket.go implement the sync command Nov 5, 2018
subscribe.go introduce the tick command/event Mar 10, 2018
subscribe_test.go reduce shared memory logfile size from 25M to 5M May 5, 2018
sync.go implement the sync command Nov 5, 2018
sync_test.go add sync_test Nov 5, 2018
tick.go introduce the tick command/event Mar 10, 2018
tree.go node: add window properties (title, class, role) (#1) May 5, 2018
validpid.go Initial commit Sep 29, 2017
version.go Initial commit Sep 29, 2017
workspaces.go Initial commit Sep 29, 2017

README.md

Build Status Go Report Card GoDoc

Package i3 provides a convenient interface to the i3 window manager via its IPC interface.

See its documentation for more details.

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