-# autorandr
+# autorandr
+
Automatically select a display configuration based on connected devices
## Branch information
This is a compatible Python rewrite of
-[wertarbyte/autorandr](https://github.com/wertarbyte/autorandr).
+[wertarbyte/autorandr](https://github.com/wertarbyte/autorandr). Contributions
+for bash-completion, fd.o/XDG autostart, Nitrogen, pm-utils, and systemd can be
+found under [contrib](contrib/).
The original [wertarbyte/autorandr](https://github.com/wertarbyte/autorandr)
tree is unmaintained, with lots of open pull requests and issues. I forked it
[#8](https://github.com/phillipberndt/autorandr/issues/8) and
especially
[#12](https://github.com/phillipberndt/autorandr/issues/12)
-if you are unhappy with this version and would like to contibute to the bash
+if you are unhappy with this version and would like to contribute to the bash
version.
## License information and authors
Contributors to this version of autorandr are:
+* Adrián López
+* andersonjacob
* Alexander Wirt
+* Brice Waegeneire
* Chris Dunder
+* Christoph Gysin
* Daniel Hahler
* Maciej Sitarz
* Mathias Svensson
* Nazar Mokrynskyi
* Phillip Berndt
* Rasmus Wriedt Larsen
+* Simon Wydooghe
* Stefan Tomanek
+* stormc
+* tachylatus
* Timo Bingmann
+* Timo Kaufmann
* Tomasz Bogdal
* Victor Häggqvist
-* stormc
-* tachylatus
-* andersonjacob
-* Simon Wydooghe
+* Jan-Oliver Kaiser
## Installation/removal
+
You can use the `autorandr.py` script as a stand-alone binary. If you'd like to
install it as a system-wide application, there is a Makefile included that also
places some configuration files in appropriate directories such that autorandr
is invoked automatically when a monitor is connected or removed, the system
-wakes up from suspend, or a user logs into an X11 session.
+wakes up from suspend, or a user logs into an X11 session. Run `make install`
+as root to install it.
-For Debian-based distributions (including Ubuntu) it is recommended to call
-`make deb` to obtain a package that can be installed and removed with `dpkg`.
+If you prefer to have a system wide install managed by your package manager,
+you can
-On Arch Linux, there is [an aur package
-available](https://aur.archlinux.org/packages/autorandr-git/).
-
-On other distributions you can install autorandr by calling `make install` and
-remove it by calling `make uninstall`. Run `make` without arguments to obtain a
-list of what exactly will be installed.
+* Use the [aur package](https://aur.archlinux.org/packages/autorandr-git/) on Arch
+* Use the [official Debian package](https://packages.debian.org/sid/x11/autorandr) on sid
+* Use the [ebuild from zugaina](https://gpo.zugaina.org/x11-misc/autorandr) on Gentoo.
+* Use the
+ [nix package](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/misc/autorandr.nix)
+ on NixOS.
+* Use the automated nightlies generated by the
+ [openSUSE build service](https://build.opensuse.org/package/show/home:phillipberndt/autorandr)
+ for various distributions (RPM and DEB based).
+* Use the [X binary package system](https://wiki.voidlinux.eu/XBPS)' on Void Linux
+* Build a .deb-file from the source tree using `make deb`.
We appreciate packaging scripts for other distributions, please file a pull
request if you write one.
+If you prefer `pip` over your package manager, you can install autorandr with:
+
+ sudo pip install "git+http://github.com/phillipberndt/autorandr#egg=autorandr"
+
+or simply
+
+ sudo pip install autorandr
+
+if you prefer to use a stable version.
+
## How to use
Save your current display configuration and setup with:
mobile
docked (detected)
-To automatically reload your setup, just append `--change` to the command line
+To automatically reload your setup:
+
+ $ autorandr --change
+
+To manually load a profile:
+
+ $ autorandr --load <profile>
-To manually load a profile, you can use the `--load <profile>` option.
+or simply:
+
+ $ autorandr <profile>
autorandr tries to avoid reloading an identical configuration. To force the
-(re)configuration, apply `--force`.
+(re)configuration:
+
+ $ autorandr --load <profile> --force
To prevent a profile from being loaded, place a script call _block_ in its
directory. The script is evaluated before the screen setup is inspected, and
as the default configuration without you having to change the system-wide
configuration.
-Another script called `postswitch` can be placed in the directory
-`~/.config/autorandr` (or `~/.autorandr` if you have an old installation) as
-well as in all profile directories: The scripts are executed after a mode
-switch has taken place and can notify window managers or other applications
-about it. The same holds for `preswitch`, which is executed before the switch
-takes place, and `postsave`, which is executed after a profile was
-stored/altered.
+You can store default values for any option in an INI-file in
+`~/.config/autorandr/settings.ini` in a section `config`. The most useful
+candidate for doing that is `skip-options`, if you need it.
+
+## Advanced usage
+
+### Hook scripts
+
+Three more scripts can be placed in the configuration directory (as
+(as defined by the [XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
+usually `~/.config/autorandr` or `~/.autorandr` if you have an old installation
+for user configuration and `/etc/xdg/autorandr` for system wide configuration):
+
+- `postswitch` is executed *after* a mode switch has taken place. This can be
+ used to notify window managers or other applications about the switch.
+- `preswitch` is executed *before* a mode switch takes place.
+- `postsave` is executed after a profile was stored or altered.
+- `predetect` is executed before autorandr attempts to run xrandr.
-All scripts can also be placed in any of the `$XDG_CONFIG_DIRS`. In addition to
-the script names themselves, any executables in subdirectories named
-`script_name.d` (e.g. `postswitch.d`) are executed as well. In scripts, some of
-autorandr's state is exposed as environment variables prefixed with `AUTORANDR_`.
-The most useful one is `$AUTORANDR_CURRENT_PROFILE`.
+These scripts must be executable and can be placed directly in the configuration
+directory, where they will always be executed, or in the profile subdirectories,
+where they will only be executed on changes regarding that specific profile.
+
+Instead (or in addition) to these scripts, you can also place as many executable
+files as you like in subdirectories called `script_name.d` (e.g. `postswitch.d`).
+
+If a script with the same name occurs multiple times, user configuration
+takes precedence over system configuration (as specified by the
+[XDG spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html))
+and profile configuration over general configuration.
+
+As a concrete example, suppose you have the files
+
+- `/etc/xdg/autorandr/postswitch`
+- `~/.config/autorandr/postswitch`
+- `~/.config/autorandr/postswitch.d/notify-herbstluftwm`
+- `~/.config/autorandr/docked/postswitch`
+
+and switch from `mobile` to `docked`. Then
+`~/.config/autorandr/docked/postswitch` is executed, since the profile specific
+configuration takes precedence, and
+`~/.config/autorandr/postswitch.d/notify-herbstluftwm` is executed, since
+it has a unique name.
+
+If you switch back from `docked` to `mobile`, `~/.config/autorandr/postswitch`
+is executed instead of the `mobile` specific `postswitch`.
+
+In these scripts, some of autorandr's state is exposed as environment variables
+prefixed with `AUTORANDR_`, such as:
+- `AUTORANDR_CURRENT_PROFILE`
+- `AUTORANDR_CURRENT_PROFILES`
+- `AUTORANDR_PROFILE_FOLDER`
+- `AUTORANDR_MONITORS`
+
+If you experience issues with xrandr being executed too early after connecting
+a new monitor, then you can use a `predetect` script to delay the execution.
+Write e.g. `sleep 1` into that file to make autorandr wait a second before
+running `xrandr`.
+
+### Wildcard EDID matching
+
+The EDID strings in the `~/.config/autorandr/*/setup` files may contain an
+asterisk to enable wildcard matching: Such EDIDs are matched against connected
+monitors using the usual file name globbing rules. This can be used to create
+profiles matching multiple (or any) monitors.
## Changelog
+**autorandr 1.7**
+
+* *2018-09-25* Fix FB size computation with rotated screens (by @Janno, #117)
+
+**autorandr 1.6**
+
+* *2018-04-19* Bugfix: Do not load default profile unless --change is set
+* *2018-04-30* Added a `AUTORANDR_MONITORS` variable to hooks (by @bricewge, #106)
+* *2018-06-29* Fix detection of current configuration if extra monitors are active
+* *2018-07-11* Bugfix in the latest change: Correctly handle "off" minitors when comparing
+* *2018-07-19* Do not kill spawned user processes from systemd unit
+* *2018-07-20* Correctly handle "off" monitors when comparing -- fixup for another bug.
+
+**autorandr 1.5**
+
+* *2018-01-03* Add --version
+* *2018-01-04* Fixed vertical/horizontal/clone-largest virtual profiles
+* *2018-03-07* Output all non-error messages to stdout instead of stderr
+* *2018-03-25* Add --detected and --current to filter the profile list output
+* *2018-03-25* Allow wildcard matching in EDIDs
+
+**autorandr 1.4**
+
+* *2017-12-22* Fixed broken virtual profile support
+* *2017-12-14* Added support for a settings file
+* *2017-12-14* Added a virtual profile `off`, which disables all screens
+
+**autorandr 1.3**
+
+* *2017-11-13* Add a short form for `--load`
+* *2017-11-21* Fix environment stealing in `--batch` mode (See #87)
+
+**autorandr 1.2**
+
+* *2017-07-16* Skip `--panning` unless it is required (See #72)
+* *2017-10-13* Add `clone-largest` virtual profile
+
+**autorandr 1.1**
+
+* *2017-06-07* Call systemctl with `--no-block` from udev rule (See #61)
+* *2017-01-20* New script hook, `predetect`
+* *2017-01-18* Accept comments (lines starting with `#`) in config/setup files
+
+**autorandr 1.0**
+
+* *2016-12-07* Tag the current code as version 1.0.0; see github issue #54
* *2016-10-03* Install a desktop file to `/etc/xdg/autostart` by default
projects / deb_pkgs / autorandr.git / blobdiff