README.md

   1 # autorandr
   2 Automatically select a display configuration based on connected devices
   3
   4 ## Branch information
   5
   6 This is a compatible Python rewrite of
   7 [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/).
   8
   9 The original [wertarbyte/autorandr](https://github.com/wertarbyte/autorandr)
  10 tree is unmaintained, with lots of open pull requests and issues. I forked it
  11 and merged what I thought were the most important changes. If you are searching
  12 for that version, see the [`legacy` branch](https://github.com/phillipberndt/autorandr/tree/legacy).
  13 Note that the Python version is better suited for non-standard configurations,
  14 like if you use `--transform` or `--reflect`. If you use `auto-disper`, you
  15 have to use the bash version, as there is no disper support in the Python
  16 version (yet). Both versions use a compatible configuration file format, so
  17 you can, to some extent, switch between them.  I will maintain the `legacy`
  18 branch until @wertarbyte finds the time to maintain his branch again.
  19
  20 If you are interested in why there are two versions around, see
  21 [#7](https://github.com/phillipberndt/autorandr/issues/7),
  22 [#8](https://github.com/phillipberndt/autorandr/issues/8) and
  23 especially
  24 [#12](https://github.com/phillipberndt/autorandr/issues/12)
  25 if you are unhappy with this version and would like to contibute to the bash
  26 version.
  27
  28 ## License information and authors
  29
  30 autorandr is available under the terms of the GNU General Public License
  31 (version 3).
  32
  33 Contributors to this version of autorandr are:
  34
  35 * Adrián López
  36 * andersonjacob
  37 * Alexander Wirt
  38 * Chris Dunder
  39 * Daniel Hahler
  40 * Maciej Sitarz
  41 * Mathias Svensson
  42 * Matthew R Johnson
  43 * Nazar Mokrynskyi
  44 * Phillip Berndt
  45 * Rasmus Wriedt Larsen
  46 * Simon Wydooghe
  47 * Stefan Tomanek
  48 * stormc
  49 * tachylatus
  50 * Timo Bingmann
  51 * Tomasz Bogdal
  52 * Victor Häggqvist
  53
  54 ## Installation/removal
  55 You can use the `autorandr.py` script as a stand-alone binary. If you'd like to
  56 install it as a system-wide application, there is a Makefile included that also
  57 places some configuration files in appropriate directories such that autorandr
  58 is invoked automatically when a monitor is connected or removed, the system
  59 wakes up from suspend, or a user logs into an X11 session.
  60
  61 For Debian-based distributions (including Ubuntu) it is recommended to call
  62 `make deb` to obtain a package that can be installed and removed with `dpkg`.
  63
  64 On Arch Linux, there is [an aur package
  65 available](https://aur.archlinux.org/packages/autorandr-git/).
  66
  67 autorandr is also packaged in the [nix package manager](https://nixos.org/nix/)
  68 repositories.
  69
  70 On other distributions you can install autorandr by calling `make install` and
  71 remove it by calling `make uninstall`. Run `make` without arguments to obtain a
  72 list of what exactly will be installed.
  73
  74 We appreciate packaging scripts for other distributions, please file a pull
  75 request if you write one.
  76
  77 If you prefer `pip` over your package manager, you can install autorandr with:
  78
  79     sudo pip install "git+http://github.com/phillipberndt/autorandr#egg=autorandr"
  80
  81 or simply
  82
  83         sudo pip install autorandr
  84
  85 if you prefer to use a stable version.
  86
  87 Automatically generated packages versions are available from the
  88 [openSUSE build service](https://build.opensuse.org/package/show/home:phillipberndt/autorandr).
  89
  90 ## How to use
  91
  92 Save your current display configuration and setup with:
  93
  94     autorandr --save mobile
  95
  96 Connect an additional display, configure your setup and save it:
  97
  98     autorandr --save docked
  99
 100 Now autorandr can detect which hardware setup is active:
 101
 102     $ autorandr
 103       mobile
 104       docked (detected)
 105
 106 To automatically reload your setup, just append `--change` to the command line
 107
 108 To manually load a profile, you can use the `--load <profile>` option.
 109
 110 autorandr tries to avoid reloading an identical configuration. To force the
 111 (re)configuration, apply `--force`.
 112
 113 To prevent a profile from being loaded, place a script call _block_ in its
 114 directory. The script is evaluated before the screen setup is inspected, and
 115 in case of it returning a value of 0 the profile is skipped. This can be used
 116 to query the status of a docking station you are about to leave.
 117
 118 If no suitable profile can be identified, the current configuration is kept.
 119 To change this behaviour and switch to a fallback configuration, specify
 120 `--default <profile>`. The system-wide installation of autorandr by default
 121 calls autorandr with a parameter `--default default`. There are three special,
 122 virtual configurations called `horizontal`, `vertical` and `common`. They
 123 automatically generate a configuration that incorporates all screens
 124 connected to the computer. You can symlink `default` to one of these
 125 names in your configuration directory to have autorandr use any of them
 126 as the default configuration without you having to change the system-wide
 127 configuration.
 128
 129 Another script called `postswitch` can be placed in the directory
 130 `~/.config/autorandr` (or `~/.autorandr` if you have an old installation) as
 131 well as in all profile directories: The scripts are executed after a mode
 132 switch has taken place and can notify window managers or other applications
 133 about it. The same holds for `preswitch`, which is executed before the switch
 134 takes place, and `postsave`, which is executed after a profile was
 135 stored/altered.
 136
 137 If you experience issues with xrandr being executed too early after connecting
 138 a new monitor, then you can create a script `predetect`, which will be executed
 139 before autorandr attempts to run xrandr. Place e.g. `sleep 1` into that file
 140 to make autorandr wait a second before running xrandr.
 141
 142 All scripts can also be placed in any of the `$XDG_CONFIG_DIRS`. In addition to
 143 the script names themselves, any executables in subdirectories named
 144 `script_name.d` (e.g. `postswitch.d`) are executed as well. In scripts, some of
 145 autorandr's state is exposed as environment variables prefixed with `AUTORANDR_`.
 146 The most useful one is `$AUTORANDR_CURRENT_PROFILE`.
 147
 148 ## Changelog
 149
 150 **autorandr 1.2**
 151
 152 * *2017-07-16* Skip `--panning` unless it is required (See #72)
 153 * *2017-10-13* Add `clone-largest` virtual profile
 154
 155 **autorandr 1.1**
 156
 157 * *2017-06-07* Call systemctl with `--no-block` from udev rule (See #61)
 158 * *2017-01-20* New script hook, `predetect`
 159 * *2017-01-18* Accept comments (lines starting with `#`) in config/setup files
 160
 161 **autorandr 1.0**
 162
 163 * *2016-12-07* Tag the current code as version 1.0.0; see github issue #54
 164 * *2016-10-03* Install a desktop file to `/etc/xdg/autostart` by default