monconf is utility for creating persistent xrandr configurations. It's
particularly useful when having different screen setups for a single machine:
e.g. for a laptop which can either use internal display or external monitors
monconf is a single script. Just drop it to your `$PATH`, e.g. to
* Python 3.5+
monconf will search for configuration file under the following path:
`~/.config/monconf/config.yml`. You can also change configuration path with *-c
Configuration is a standard YAML file. You can find an example configuration in
Configuration has 2 main sections:
* *outputs*: a section where xrandr-compatible outputs and their default options
* *configurations*: a section where xrandr configurations are described
Outputs section contains a list of xrandr outputs. Each of these might have one
of the following properties:
* *name*: same name of output as given by `xrandr`
* *mode*: (optional) mode which will be configured for xrandr. If omitted,
`auto` mode will be used, otherwise it should be any of the modes reported by
`xrandr`. It's disregarded (changed to *off*) when output is disabled for
* *options*: (optional) list of options which will be directly translated to
xrandr arguments. For example:
- crtc: 1
- right-of: VGA1
will be translated to: `--primary --crtc 1 --right-of VGA1`.
TIP: You don't have to specify _outputs_ section if you don't want to invoke
Configurations section contains a list of options which will be translated to
xrandr invocations. Each configuration have the following properties:
* *name*: name under which configuration is known. This is the name passed as
* *enable*: (optional) list of outputs which should be enabled by this
configuration. Can be a single output as well.
* *disable*: (optional) list of outputs which should be disabled by this
configuration. By default (if it's not specified), all outputs not listed in
*enable* field are disabled. If you don't want to disable any outputs, pass an
* *post_conf*: (optional) list of commands which will be executed after
*successfull* xrandr command (not running xrandr command at all e.g. because
there were no outputs to enable or disable is considered successfull as well).
Commands will stop on first failure. You can mark a command which can fail by
placing a leading *minus sign* `-`, similar to `make` recipes:
- echo "OK"
- -exit 1
- echo "I'm still OK"
* *on_error*: (optional) works the same way as *post_conf*, but commands will be
executed only after xrandr's failure.
* *standalone*: (optional) boolean (true/false) which, when set to true, removes
this configuration from a list which will be automatically cycled when
configuration name is not passed to monconf. By default all configurations
marked as not standalone (i.e. will be cycled through).
== Selecting a configuration
There are 3 ways to choose a configuration which will be used:
1. by passing it explicitly to monconf:
$ monconf configuration-name
2. by creating a temporary simple configuration from configured outputs:
$ monconf -e HDMI-1,VGA-2
3. by not telling monconf anything in which case it will cycle non-standalone