README.md

   1 # autorandr
   2
   3 Automatically select a display configuration based on connected devices
   4
   5 Stefan Tomanek <[stefan.tomanek@wertarbyte.de](stefan.tomanek@wertarbyte.de)>
   6
   7 ## Branch information
   8
   9 The original wertarbyte/autorandr tree seems unmaintained, with lots of open
  10 pull requests and issues. I forked it and merged what I thought were the most
  11 important changes. I will maintain this branch until wertarbyte finds the time
  12 to maintain his branch again.
  13
  14 ## License information and authors
  15
  16 autorandr was originally written by Stefan Tomanek and not published under any
  17 Open Source license. He did so far not respond to requests regarding the code's
  18 license. In this fork, all code has been reimplemented by various authors that
  19 have agreed to release their code under the terms of the GNU General Public
  20 License (version 3).
  21
  22 Note that this license only applies to versions of autorandr from this fork
  23 that are committed after issue #7 is closed, and versions derived from that
  24 one. In particular, wertarbyte's original repository is still not OSS.
  25
  26 ## How to use
  27
  28 Save your current display configuration and setup with:
  29 ```
  30 autorandr --save mobile
  31 ```
  32
  33 Connect an additional display, configure your setup and save it:
  34 ```
  35 autorandr --save docked
  36 ```
  37
  38 Now autorandr can detect which hardware setup is active:
  39 ```
  40  $ autorandr
  41    mobile
  42    docked (detected)
  43 ```
  44
  45 To automatically reload your setup, just append `--change` to the command line
  46
  47 To manually load a profile, you can use the `--load <profile>` option.
  48
  49 autorandr tries to avoid reloading an identical configuration. To force the
  50 (re)configuration, apply `--force`.
  51
  52 To prevent a profile from being loaded, place a script call _block_ in its
  53 directory. The script is evaluated before the screen setup is inspected, and
  54 in case of it returning a value of 0 the profile is skipped. This can be used
  55 to query the status of a docking station you are about to leave.
  56
  57 If no suitable profile can be identified, the current configuration is kept.
  58 To change this behaviour and switch to a fallback configuration, specify
  59 `--default <profile>`.
  60
  61 Another script called `postswitch` can be placed in the directory
  62 `~/.autorandr` as well as in all profile directories: The scripts are executed
  63 after a mode switch has taken place and can notify window managers or other
  64 applications about it.
  65
  66 While the script uses xrandr by default, calling it by the name `autodisper`
  67 or `auto-disper` forces it to use the [disper](http://willem.engen.nl/projects/disper/)
  68 utility, which is useful for controlling nvidia chipsets. The formats for
  69 fingerprinting the current setup and saving/loading the current configuration
  70 are adjusted accordingly.
  71
  72 To install autorandr call `make install`, define your setup and then call
  73 `make hotplug` to install hotplug scripts.
  74
  75 For Debian using auto-disper:
  76 To make the screen auto-configure when your computer wakes up,
  77 * Copy auto-disper into /usr/local/bin/
  78 * Copy pm-utils/40auto-disper into /etc/pm/sleep.d/
  79 * (Assuming gnome) Run gnome-keybinding-properties and ADD a shortcut,
  80   I called it "Run auto-disper", I set it to CTRL-F7, and the command is:
  81   `auto-disper -c --default default`
  82 * Create a default disper setting... eg for laptop: unplug all monitors,
  83   set up the screen nicely on the laptop display.
  84   Then run `auto-disper --save laptop`