https://wiki.archlinux.org/api.php?action=feedcontributions&user=Airblader&feedformat=atomArchWiki - User contributions [en]2024-03-28T10:43:44ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=PulseAudio&diff=699942PulseAudio2021-10-25T13:58:25Z<p>Airblader: Mention lsp-plugins</p>
<hr />
<div>[[Category:Sound]]<br />
[[cs:PulseAudio]]<br />
[[de:Pulseaudio]]<br />
[[fr:PulseAudio]]<br />
[[it:PulseAudio]]<br />
[[ja:PulseAudio]]<br />
[[pt:PulseAudio]]<br />
[[ru:PulseAudio]]<br />
[[zh-hans:PulseAudio]]<br />
{{Related articles start}}<br />
{{Related|PulseAudio/Examples}}<br />
{{Related|PulseAudio/Troubleshooting}}<br />
{{Related|PipeWire}}<br />
{{Related articles end}}<br />
[[Wikipedia:PulseAudio|PulseAudio]] is a general purpose sound server intended to run as a middleware between your applications and your hardware devices, either using [[ALSA]] or [[OSS]]. It also offers easy network streaming across local devices using [[Avahi]] if enabled. While its main purpose is to ease audio configuration, its modular design allows more advanced users to configure the daemon precisely to best suit their needs.<br />
<br />
{{Note|Some confusion may occur between [[ALSA]] and PulseAudio. ALSA includes a Linux kernel component with sound card drivers, as well as a userspace component, {{ic|libasound}}.[https://www.alsa-project.org/main/index.php/Download] PulseAudio builds only on the kernel component, but offers compatibility with {{ic|libasound}} through {{Pkg|pulseaudio-alsa}}.[https://www.freedesktop.org/wiki/Software/PulseAudio/FAQ/#index14h3]}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|pulseaudio}} package.<br />
<br />
Some PulseAudio modules are not included in the main package and must be installed separately if needed:<br />
<br />
* {{Pkg|pulseaudio-alsa}} for PulseAudio to manage [[ALSA]] as well, see [[#ALSA]]<br />
* {{Pkg|pulseaudio-bluetooth}} for [[bluetooth]] support (Bluez), see [[bluetooth headset]] page<br />
* {{Pkg|pulseaudio-equalizer}} for equalizer sink (qpaeq)<br />
* {{Pkg|pulseaudio-jack}} for [[JACK]] sink, source and jackdbus detection<br />
* {{Pkg|pulseaudio-lirc}} for infrared volume control with [[LIRC]]<br />
* {{Pkg|pulseaudio-zeroconf}} for Zeroconf ([[Avahi]]/DNS-SD) support<br />
<br />
=== Front-ends ===<br />
<br />
There are a number of front-ends available for controlling the PulseAudio daemon:<br />
<br />
==== Console ====<br />
<br />
* {{App|ncpamixer|Ncurses mixer for PulseAudio inspired by pavucontrol.|https://github.com/fulhax/ncpamixer|{{AUR|ncpamixer}}}}<br />
* {{App|pacmixer|Alsamixer alike for PulseAudio.|https://github.com/KenjiTakahashi/pacmixer|{{AUR|pacmixer}}}}<br />
* {{App|PAmix|Ncurses PulseAudio mixer similar to pavucontrol.|https://github.com/patroclos/PAmix|{{AUR|pamix-git}}}}<br />
* {{App|pamixer|PulseAudio command line mixer.|https://github.com/cdemoulins/pamixer|{{Pkg|pamixer}}}}<br />
* {{App|pavolume|Simple command-line volume control for PulseAudio with libnotify messages.|https://github.com/sseemayer/pavolume|{{AUR|pavolume-git}}}}<br />
* {{App|Ponymix|Command line mixer for PulseAudio.|https://github.com/falconindy/ponymix|{{AUR|ponymix}}}}<br />
* {{App|pulseaudio-ctl|Control PulseAudio volume from the shell or mapped to keyboard shortcuts.|https://github.com/graysky2/pulseaudio-ctl|{{AUR|pulseaudio-ctl}}}}<br />
* {{App|pulsemixer|CLI and curses mixer for PulseAudio|https://github.com/GeorgeFilipkin/pulsemixer|{{Pkg|pulsemixer}}}}<br />
<br />
==== Graphical ====<br />
<br />
* {{App|KMix|[[KDE]] volume control application supporting several platforms including PulseAudio, system tray applet configurable.|https://apps.kde.org/kmix/|{{pkg|kmix}}}}<br />
* {{App|MicTray|Lightweight system tray application which lets you control the microphone state and volume using PulseAudio.|https://github.com/Junker/MicTray|{{AUR|mictray}}}}<br />
* {{App|pa-applet|System tray applet for PulseAudio with volume bar.|https://github.com/fernandotcl/pa-applet|{{AUR|pa-applet-git}}}}<br />
* {{App|pasystray|System tray applet for PulseAudio.|https://github.com/christophgysin/pasystray|{{Pkg|pasystray}}}}<br />
* {{App|plasma-pa|[[KDE]] Plasma applet for audio volume management using PulseAudio|https://invent.kde.org/plasma/plasma-pa|{{Pkg|plasma-pa}}}}<br />
* {{App|PulseAudio Equalizer|LADSPA based multiband equalizer for PulseAudio.|https://github.com/pulseaudio-equalizer-ladspa/equalizer|{{Pkg|pulseaudio-equalizer-ladspa}}}}<br />
* {{App|PulseAudio Graph Control|Electron-based volume and graph control for PulseAudio.|https://github.com/futpib/pagraphcontrol#readme|{{AUR|pagraphcontrol-git}}}}<br />
* {{App|PulseAudio Manager|Simple GTK frontend for PulseAudio. Discontinued development.|http://0pointer.de/lennart/projects/paman/|{{AUR|paman}}}}<br />
* {{App|PulseAudio Preferences|Simple GTK configuration dialog for PulseAudio.|https://freedesktop.org/software/pulseaudio/paprefs/|{{Pkg|paprefs}}}}<br />
* {{App|PulseAudio Volume Control|Simple GTK volume control tool ("mixer") for PulseAudio.|https://freedesktop.org/software/pulseaudio/pavucontrol/|{{Pkg|pavucontrol}}}}<br />
* {{App|PulseAudio Volume Control (Qt)|Mixer for PulseAudio (Qt port of pavucontrol).|https://github.com/lxqt/pavucontrol-qt|{{Pkg|pavucontrol-qt}}}}<br />
* {{App|PulseAudio Volume Control (Sandsmark)|Lightweight fork of the LXQt's pavucontrol, with missing features from pavucontrol implemented, bug fixes and unnecessary dependencies removed.|https://github.com/sandsmark/pavucontrol-qt|{{AUR|pavucontrol-qt-sandsmark-git}}}}<br />
* {{App|PulseAudio Volume Meter|Simple GTK volume meter for PulseAudio. Discontinued development.|http://0pointer.de/lennart/projects/pavumeter/|{{AUR|pavumeter}}}}<br />
* {{App|PulseEffects|Audio effects for PulseAudio applications.|https://github.com/wwmm/easyeffects/tree/pulseaudio-legacy|{{AUR|pulseeffects-legacy}}}}<br />
* {{App|Volctl|Per-application system tray applet volume control for PulseAudio.|https://buzz.github.io/volctl/|{{AUR|volctl}}}}<br />
* {{App|Xfce PulseAudio Panel Plugin|PulseAudio plugin for [[Xfce]]4 panel.|https://goodies.xfce.org/projects/panel-plugins/xfce4-pulseaudio-plugin|{{Pkg|xfce4-pulseaudio-plugin}}}}<br />
<br />
== Configuration ==<br />
<br />
By default, PulseAudio is configured to automatically detect all sound cards and manage them. It takes control of all detected ALSA devices and redirects all audio streams to itself, making the PulseAudio daemon the central configuration point. The daemon should work mostly out of the box, only requiring a few minor tweaks. <br />
<br />
While PulseAudio usually runs fine out of the box and requires only minimal configuration, advanced users can change almost every aspect of the daemon by either altering the default configuration file to disable modules or writing your own from scratch.<br />
<br />
PulseAudio runs as a server daemon that can run either system-wide or on per-user basis using a client/server architecture. The daemon by itself does nothing without its '''modules''' except to provide an API and host dynamically loaded modules. The audio routing and processing tasks are all handled by various modules, including PulseAudio's native protocol itself (provided by [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index22h3 module-native-protocol-unix]). Clients reach the server through one of many protocol modules that will accept audio from external sources, route it through PulseAudio and eventually have it go out through a final other module. The output module does not have to be an actual sound output: it can dump the stream into a file, stream it to a broadcasting server such as [[Icecast]], or even just discard it.<br />
<br />
You can find a detailed list of all available modules at [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/ Pulseaudio Loadable Modules]. To enable them you can just add a line {{ic|load-module ''module-name-from-list''}} to {{ic|~/.config/pulse/default.pa}}.<br />
<br />
=== Configuration files ===<br />
<br />
PulseAudio will first look for configuration files in the home directory {{ic|~/.config/pulse/}}, and if they are not found, the system-wide configuration from {{ic|/etc/pulse/}} will be applied.<br />
<br />
{{Tip|<br />
* It is strongly suggested not to edit system-wide configuration files, but rather edit user ones. Create the {{ic|~/.config/pulse}} directory, then copy the system configuration files into it and edit according to your need.<br />
* Make sure you keep user configuration in sync with changes to the packaged files in {{ic|/etc/pulse/}}. Otherwise, PulseAudio may refuse to start due to configuration errors.<br />
* There is usually no need to add your user to the {{ic|audio}} group, as PulseAudio uses [[udev]] and ''logind'' to give access dynamically to the currently "active" user. Exceptions would include running the machine headless so that there is no currently "active" user.<br />
}}<br />
<br />
==== daemon.conf ====<br />
<br />
This is the main configuration file to configure the daemon itself. It defines base settings like the default sample rates used by modules, resampling methods, realtime scheduling and various other settings related to the server process. These can not be changed at runtime without restarting the PulseAudio daemon. The defaults are sensible for most users, see the {{man|5|pulse-daemon.conf}} [[man page]] for additional information. Boolean options accepts any of these: {{ic|true}}, {{ic|yes}}, {{ic|on}} and {{ic|1}} as well as {{ic|false}}, {{ic|no}}, {{ic|off}} and {{ic|0}}.<br />
<br />
{{Note|PulseAudio does not perform tilde expansion on paths in this file. Use absolute paths for any files.}}<br />
<br />
{| class="wikitable"<br />
! Option || Description<br />
|+<br />
| daemonize || Controls whether the server will daemonize itself and return. Set to {{ic|no}} when debugging so you can see the debugging information on the terminal.<br />
|+<br />
| resample-method || Which resampler to use when audio with incompatible sample rates needs to be passed between modules (e.g. playback of 96kHz audio on hardware which only supports 48kHz). The available resamplers can be listed with {{ic|pulseaudio --dump-resample-methods}}. Choose the best tradeoff between CPU usage and audio quality for the present use-case. {{Tip|In some cases PulseAudio will generate a high CPU load. This can happen when multiple streams are resampled (individually). If this is a common use-case in a workflow, it should be considered to create an additional sink at a matching sample rate which can then be fed into the main sink, resampling only once.}}<br />
|+<br />
| avoid-resampling || With {{ic|1=avoid-resampling = yes}}, PulseAudio automatically configures the hardware to the sample rate which the application uses, if the hardware supports this sample rate (needs [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/11.0/ PA 11] or higher)<br />
{{Warning|Enabling this feature might cause audio distortion, therefore it is disabled by default, see the [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/11.0/ release notes] for more information.}}<br />
|+<br />
| enable-remixing || When the input and output have a different channel count (for example, outputting a 6 channel movie into a stereo sink), pulse can either remix all the channels (default, {{ic|yes}}) or just trivially map the channels by their name (left goes to left, right to right, all others ignored) when {{ic|no}}<br />
|+<br />
| system-instance || If set to {{ic|yes}}, run the daemon as a [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide/ system-wide] instance. [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide/ Highly discouraged] as it can introduce security issues. Useful on [[Xorg multiseat|Multiseat]] systems, or headless systems that have no real local users. Defaults to {{ic|no}}.<br />
|+<br />
| flat-volumes ||{{ic|flat-volumes}} scales the device-volume with the volume of the "loudest" application. For example, raising the VoIP call volume will raise the hardware volume and adjust the music-player volume so it stays where it was, without having to lower the volume of the music-player manually. Defaults to {{ic|yes}} upstream, but to {{ic|no}} within Arch. {{Note|The default behavior upstream can sometimes be confusing and some applications, unaware of this feature, can set their volume to 100% at startup, potentially blowing your speakers or your ears. This is why Arch defaults to the classic (ALSA) behavior by setting this to {{ic|no}}.}}<br />
|+<br />
| realtime-scheduling || If your [[kernel]] supports realtime scheduling (for instance, [[Realtime kernel]] or [[Linux-ck]]), set this to {{ic|yes}} to ensure PulseAudio can deliver low-latency glitch-free playback. You can adjust {{ic|realtime-priority}} as well to have it use the correct priority, especially when [[JACK]] is also running on the system.<br />
|+<br />
| nice-level || Since PulseAudio runs in userspace and involves inter-process communication, audio can be subject to dropouts if the daemon does not have enough CPU time to process the audio. The default usually is enough, but can be tweaked to give pulse the wanted priority over (or below) other applications.<br />
|+<br />
| exit-idle-time || If you want to run PulseAudio only when needed and use ALSA otherwise, you can set a delay in seconds after which the daemon will automatically shutdown after all clients are disconnected. Set it to -1 to disable this feature.<br />
|+<br />
| log-level || When debugging, you may want to increase the logging level of the daemon to see exactly why a specific module fails to load. High logging levels will sometimes print useful information such as detected minimum latency for the system, which can then be used to tweak {{ic|default-fragments}} and {{ic|default-fragment-size-msec}}.<br />
|+<br />
| default-sample-format || This usually does not need to be changed, but if your sound card's native format is different, performance and quality can be improved by setting the right format here.<br />
|+<br />
| default-sample-rate || The default sample rate user by pulse unless overriden at module level. Change this if your sound card does not support 44100Hz or if you wish to upsample all audio. See previous note about CPU usage.<br />
|+<br />
| alternate-sample-rate || To fix a common limitation where movies at 48000Hz were needlessly downsampled to 44100Hz, some modules support changing their sample rate dynamically to avoid resampling when possible. See manual for more in-depth information. This usually does not need to be changed.<br />
|+<br />
| default-channels || The default number of channels when not specified. Usually do not need any change as you can configure more channels on per-module basis.<br />
|+<br />
| default-fragments || Audio samples are split into multiple fragments of {{ic|default-fragment-size-msec}} each. The larger the buffer is, the less likely audio will skip when the system is overloaded. On the downside this will increase the overall latency. Increase this value if you have issues.<br />
|+<br />
| default-fragment-size-msec || The size in milliseconds of each fragment. This is the amount of data that will be processed at once by the daemon.<br />
|}<br />
<br />
==== default.pa ====<br />
<br />
This file is a startup script and is used to configure modules. It is actually parsed and read after the daemon has finished initializing and additional commands can be sent at runtime using {{man|1|pactl}} or {{man|1|pacmd}}. The startup script can also be provided on the command line by starting PulseAudio in a terminal using {{ic|pulseaudio -nC}}. This will make the daemon load the CLI module and will accept the configuration directly from the command line, and output resulting information or error messages on the same terminal. This can be useful when debugging the daemon or just to test various modules before setting them permanently on disk. The manual page is quite self-explanatory, consult {{man|5|pulse-cli-syntax}} for the details of the syntax.<br />
<br />
{{Tip|<br />
* Rather than being a complete copy, {{ic|~/.config/pulse/default.pa}} can start with the line {{ic|.include /etc/pulse/default.pa}} and then just override the defaults.<br />
* Run {{ic|pacmd list-sinks {{!}} grep -Ei 'index:{{!}}name:'}} to list available sinks. The present default sink is marked with an asterisk.<br />
* Edit {{ic|~/.config/pulse/default.pa}} to insert/alter the set-default-sink command using the sink's name as the numbering cannot be guaranteed repeatable.<br />
}}<br />
<br />
==== client.conf ====<br />
<br />
This is the configuration file read by every PulseAudio client application. It is used to configure runtime options for individual clients. It can be used to set and configure the default sink and source statically as well as allowing (or disallowing) clients to automatically start the server if not currently running. If autospawn is enabled, clients will automatically start PulseAudio if it is not already running when a client attempts to connect to it. This can be useful if you do not want PulseAudio to always be running to conserve system resources. Otherwise, you really should have it start with your X11 session.<br />
<br />
=== Configuration command ===<br />
<br />
The main command to configure a server during runtime is {{ic|pacmd}}. Run {{ic|pacmd --help}} for a list options, or just run {{ic|pacmd}} to enter the shell interactive mode and {{ic|Ctrl+d}} to exit. All modifications will immediately be applied.<br />
<br />
Once your new settings have been tested and meet your needs, edit the {{ic|default.pa}} accordingly to make the change persistent. See [[PulseAudio/Examples]] for some basic settings.<br />
<br />
{{Tip|Leave the {{ic|load-module module-default-device-restore}} line in the {{ic|default.pa}} file untouched. It will allow you to restart the server in its default state, thus dismissing any wrong setting.}}<br />
<br />
It is important to understand that the "sources" (processes, capture devices) and "sinks" (sound cards, servers, other processes) accessible and selectable through PulseAudio depend upon the current hardware "Profile" selected. These "Profiles" are those ALSA "pcms" listed by the command {{ic|aplay -L}}, and more specifically by the command {{ic|pacmd list-cards}}, which will include a line "index:", a list beginning "profiles:", and a line "active profile: <...>" in the output, among other things. "Profiles" correspond to different card input/output configurations, notably the number of available input/output channels.<br />
<br />
The "active profile" can be set with the command {{ic|pacmd set-card-profile INDEX PROFILE}}, with ''no'' comma separating INDEX and PROFILE, where INDEX is just the number on the line "index:" and a PROFILE name is everything shown from the beginning of any line under "profile:" to just ''before'' the colon and first space, as shown by the command {{ic|pacmd list-cards}}. For instance, {{ic|pacmd set-card-profile 0 output:analog-stereo+input:analog-stereo}}.<br />
<br />
It may be easier to select a "Profile" with a graphical tool like {{ic|pavucontrol}}, under the "Configuration" tab, or KDE System Settings, "Multimedia/Audio and Video Settings", under the "Audio Hardware Setup" tab. Each audio "Card", which are those devices listed by the command {{ic|aplay -l}}, or again by the command {{ic|pacmd list-cards}}, will have its own selectable "Profile". When a "Profile" has been selected, the then available "sources" and "sinks" can be seen by using the commands {{ic|pacmd list-sources}} and {{ic|pacmd list-sinks}}. Note that the "index" of the available sources and sinks will change each time a card profile is changed.<br />
<br />
The selected "Profile" can be an issue for some applications, especially the Adobe Flash players, typically {{ic|/usr/lib/mozilla/plugins/libflashplayer.so}} and {{ic|/usr/lib/PepperFlash/libpepflashplayer.so}}. Often, these Flash players will only work when one of the Stereo profiles is selected, and otherwise, will play video with no sound, or will simply "crash". When all else fails, you might try selecting a different profile.<br />
<br />
Of course, when configuring some variation of Surround Sound in PulseAudio, the appropriate Surround profile will have to be selected, before Surround Sound will work, or in order to do things like remap the speaker channels.<br />
<br />
=== Connection and authentication ===<br />
<br />
Since PulseAudio runs as a daemon as the current user, clients needs to know where to find the daemon socket to connect to it as well as a shared random cookie file clients use to authenticate with it. By default, clients should be able to locate the daemon without problem using environment variables, X11 root window properties and finally by trying the default location ({{ic|unix:/run/user/$ID/pulse/native}}). However, if you have clients that needs to access PulseAudio outside of your X11 session like [[mpd]] running as a different user, you will need to tell it how to connect to your PulseAudio instance. See [[PulseAudio/Examples#Allowing multiple users to share a PulseAudio daemon]] for a complete example. An authentication cookie containing random bytes is enabled by default to ensure audio does not leak from one user to another on a multi-user system. If you already control who can access the server using user/group permissions, you can disable the cookie by passing {{ic|1=auth-cookie-enabled=0}} to {{ic|module-native-protocol-unix}}.<br />
<br />
==== Environment variables ====<br />
<br />
These two variables are the important ones in order for libpulse clients to locate PulseAudio if you moved its socket to somewhere else. See {{man|1|pulseaudio}} for more details and other useful environment variables clients will read.<br />
<br />
{| class="wikitable"<br />
! Variable || Definition<br />
|+<br />
| {{ic|PULSE_SERVER}} || Defines where the server is. It takes a protocol prefix like {{ic|unix:}} or {{ic|tcp}} followed by the path or IP of the server. Example: {{ic|unix:/home/pulse/native-sock}}.<br />
|+<br />
| {{ic|PULSE_COOKIE}} || Point this to the location of a file that contains the random cookie generated by PulseAudio. This file will be read by clients and its content sent to the server, thus the file has to be readable by all audio clients. It does not need to be the same file, as long as its content matches the one the daemon uses.<br />
|}<br />
<br />
==== X11 properties ====<br />
<br />
PulseAudio also uses window properties on the root window of the X11 server to help find the daemon. Since environment variables cannot be modified after child processes are started, X11 properties are more flexible because they are more easily changed because they are globally shared. As long as applications receive a {{ic|1=DISPLAY=}} environment variable, it can read the most up-to-date values. X11 properties can be queried using {{ic|xprop -root}}, or with {{ic|pax11publish -d}} to read pulse-specific properties. {{ic|pax11publish}} can also be used to update the properties from environment variables ({{ic|pax11publish -e}}, or {{ic|pax11publish -r}} to remove them entirely). If possible, it is recommended to let PulseAudio do it by itself using the module-x11-publish module or the {{ic|start-pulseaudio-x11}} command. The following table is there only for completeness, you should not ever need to manually set these variables by hand.<br />
<br />
{| class="wikitable"<br />
! Variable || Definition<br />
|+<br />
| {{ic|PULSE_SERVER}} || String value ({{ic|xprop -root -f PULSE_SERVER 8s -set PULSE_SERVER "unix:/tmp/pulse-sock"}}), works the same as the environment variable of the same name.<br />
|+<br />
| {{ic|PULSE_COOKIE}} || String value that contains the hexadecimal representation of the authentication cookie.<br />
|}<br />
<br />
== Running ==<br />
<br />
PulseAudio on Arch has {{ic|pulseaudio.socket}} enabled by default for the [[systemd/User]] instance. This means that PulseAudio will automatically start when needed.<br />
<br />
{{Note|<br />
* To disable {{ic|pulseaudio.socket}}, make sure that {{ic|$XDG_CONFIG_HOME/systemd/user/}} exists and run {{ic|systemctl --user mask pulseaudio.socket}}.<br />
* Many [[desktop environments]] support [[XDG Autostart]]. In those desktop environments, PulseAudio will be launched automatically regardless of the socket activation status.<br />
}}<br />
<br />
For more information, see [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Running/ PulseAudio: Running].<br />
<br />
== Stopping ==<br />
<br />
[[Stop]] the {{ic|pulseaudio.socket}} and {{ic|pulseaudio.service}} user units.<br />
<br />
== Back-end configuration ==<br />
<br />
=== ALSA ===<br />
<br />
{{Warning|Do '''not''' attempt to change the ALSA configuration files while using the default PulseAudio configuration. The default configuration grabs the hardware devices directly in order to allow all the on-the-fly configurations using the GUIs. Changes to the ALSA configurations will very likely be ignored by PulseAudio and ALSA applications will break randomly while trying to access an ALSA device already used by PulseAudio. If you intend to change the ALSA configurations, also configure PulseAudio manually to output to your own ALSA device and play nice with your configuration.}}<br />
<br />
If you have applications that do not support PulseAudio explicitly but rely on ALSA, these applications will try to access the sound card directly via ALSA and will therefore bypass PulseAudio. PulseAudio will thus not have access to the sound card any more. As a result, all applications relying on PulseAudio will not be working any more, leading to [[PulseAudio/Troubleshooting#The only device shown is "dummy output" or newly connected cards are not detected|this issue]]. To prevent this, you will need to install the {{Pkg|pulseaudio-alsa}} package. It contains the necessary {{ic|/etc/alsa/conf.d/99-pulseaudio-default.conf}} for configuring ALSA to use PulseAudio. Also make sure that {{ic|~/.asoundrc}} does not exist, as it would override the {{ic|/etc/asound.conf}} file.<br />
<br />
Also install {{Pkg|lib32-libpulse}} and {{Pkg|lib32-alsa-plugins}} if you run a x86_64 system and want to have sound for 32-bit [[multilib]] programs like [[Wine]] and [[Steam]].<br />
<br />
To prevent applications from using ALSA's OSS emulation and bypassing PulseAudio (thereby preventing other applications from playing sound), make sure the module {{ic|snd_pcm_oss}} is not being loaded at boot. If it is currently loaded ({{ic|<nowiki>lsmod | grep oss</nowiki>}}), disable it by executing:<br />
# rmmod snd_pcm_oss<br />
<br />
==== Enable DTS via ALSA ====<br />
<br />
To enable PulseAudio DTS (Digital Theater System) via ALSA install {{aur|dcaenc}} package and enable it:<br />
<br />
{{hc|/etc/asound.conf|2=<br />
<confdir:pcm/dca.conf><br />
}}<br />
<br />
Finally restart PulseAudio. If experience volume issues with your DTS device and/or PulseAudio, you may fix it by looking for more setting option at [https://github.com/darealshinji/dcaenc dcaenc's Github].<br />
<br />
==== Expose PulseAudio sources, sinks and mixers to ALSA ====<br />
<br />
Although {{Pkg|pulseaudio-alsa}} contains the necessary configuration file to allow ALSA applications to use PulseAudio's default device, ALSA's {{ic|pulse}} plugin is more versatile than that:<br />
<br />
{{hc|~/.asoundrc (or /etc/asound.conf)|2=<br />
# Create an alsa input/output using specific PulseAudio sources/sinks<br />
pcm.pulse-example1 {<br />
type pulse<br />
device "my-combined-sink" # name of a source or sink<br />
fallback "pulse-example2" # if combined not available<br />
}<br />
<br />
pcm.pulse-example2 {<br />
type pulse<br />
device "other-sound-card" # name of a source or sink<br />
# example: device "alsa_output.pci-0000_00_1b.0.analog-stereo"<br />
}<br />
<br />
# Create an alsa mixer using specific PulseAudio sources/sinks<br />
# these can be tested with "alsamixer -D pulse-example3"<br />
ctl.pulse-example3 {<br />
type pulse<br />
device "my-output" # name of source or sink to control<br />
<br />
# example: always control the laptop speakers:<br />
# device "alsa_output.pci-0000_00_1b.0.analog-stereo"<br />
fallback "pulse-example4" # supports fallback too<br />
}<br />
<br />
# Mixers also can control a specific source and sink, separately:<br />
ctl.pulse-example4 {<br />
type pulse<br />
sink "my-usb-headphones"<br />
source "my-internal-mic"<br />
<br />
# example: output to HDMI, record using internal<br />
sink "alsa_output.pci-0000_01_00.1.hdmi-stereo-extra1"<br />
source "alsa_input.pci-0000_00_1b.0.analog-stereo"<br />
}<br />
<br />
# These can override the default mixer (example: for pnmixer integration)<br />
ctl.!default {<br />
type pulse<br />
sink "alsa_output.pci-0000_01_00.1.hdmi-stereo-extra1"<br />
source "alsa_input.pci-0000_00_1b.0.analog-stereo"<br />
}<br />
}}<br />
<br />
The [https://git.alsa-project.org/?p=alsa-plugins.git;a=tree;f=pulse;hb=HEAD source code] can be read to know all available options.<br />
<br />
==== ALSA/dmix without grabbing hardware device ====<br />
<br />
{{Note|This section describes alternative configuration, which is generally '''not''' recommended.}}<br />
<br />
You may want to use ALSA directly in most of your applications while still being able to use applications which require PulseAudio at the same time. The following steps allow you to make PulseAudio use dmix instead of grabbing ALSA hardware device.<br />
<br />
* Remove package {{Pkg|pulseaudio-alsa}}, which provides compatibility layer between ALSA applications and PulseAudio. After this your ALSA apps will use ALSA directly without being hooked by Pulse.<br />
<br />
* Create a configuration file in {{ic|/etc/pulse/default.pa.d/}} to unload the autodetection modules and load back-end drivers statically. Add '''device''' parameters as follows:<br />
<br />
{{hc|/etc/pulse/default.pa.d/load-audio-drivers-statically.pa|2=<br />
unload-module module-udev-detect<br />
unload-module module-detect<br />
load-module module-alsa-sink '''device=dmix'''<br />
load-module module-alsa-source '''device=dsnoop'''<br />
}}<br />
<br />
* ''Optional:'' If you use {{Pkg|kmix}} you may want to control ALSA volume instead of PulseAudio volume:<br />
<br />
$ echo export KMIX_PULSEAUDIO_DISABLE=1 > ~/.kde4/env/kmix_disable_pulse.sh<br />
$ chmod +x ~/.kde4/env/kmix_disable_pulse.sh<br />
<br />
* Now, reboot your computer and try running ALSA and PulseAudio applications at the same time. They both should produce sound simultaneously.<br />
:Use {{Pkg|pavucontrol}} to control PulseAudio volume if needed.<br />
<br />
=== OSS ===<br />
<br />
There are multiple ways of making OSS-only programs output to PulseAudio:<br />
<br />
==== ossp ====<br />
<br />
Install {{Pkg|ossp}} package and start {{ic|osspd.service}}.<br />
<br />
==== padsp wrapper ====<br />
<br />
Programs using OSS can work with PulseAudio by starting it with padsp (included with PulseAudio):<br />
<br />
$ padsp OSSprogram<br />
<br />
A few examples:<br />
<br />
$ padsp aumix<br />
$ padsp sox foo.wav -t ossdsp /dev/dsp<br />
<br />
You can also add a custom wrapper script like this: <br />
<br />
{{hc|/usr/local/bin/OSSProgram|<br />
#!/bin/sh<br />
exec padsp /usr/bin/OSSprogram "$@"<br />
}}<br />
<br />
Make sure {{ic|/usr/local/bin}} comes before {{ic|/usr/bin}} in your {{ic|PATH}}.<br />
<br />
{{Note|This does not work when the module-udev-detect has the option {{ic|1=tsched=0}}.}}<br />
<br />
=== GStreamer ===<br />
<br />
Install {{Pkg|gst-plugins-good}}, or {{AUR|gstreamer0.10-good-plugins}} if your intended program has a legacy [[GStreamer]] implementation.<br />
<br />
=== OpenAL ===<br />
<br />
OpenAL Soft should use PulseAudio by default, but can be explicitly configured to do so: {{hc|/etc/openal/alsoft.conf|2=drivers=pulse,alsa}}<br />
<br />
By default, OpenAL does not allow pulseaudio to move audio streams to a different device. To change this, add the allow-moves option:<br />
<br />
{{hc|/etc/openal/alsoft.conf|2=<br />
[pulse]<br />
allow-moves=true<br />
}}<br />
<br />
=== libao ===<br />
<br />
Edit the libao configuration file:<br />
{{hc|/etc/libao.conf|2=default_driver=pulse}}<br />
Be sure to remove the {{ic|1=dev=default}} option of the alsa driver or adjust it to specify a specific Pulse sink name or number. <br />
<br />
{{Note|You could possibly also keep the libao standard of outputting to the ''alsa'' driver and its default device if you install {{pkg|pulseaudio-alsa}} since the ALSA default device then '''is''' PulseAudio.}}<br />
<br />
== Audio post-processing ==<br />
<br />
=== PulseEffects ===<br />
<br />
[https://github.com/wwmm/easyeffects/tree/pulseaudio-legacy PulseEffects] is a GTK advanced utility for applying several audio effects (e.g. Noise reduction, Equalizer etc.) to audio input and output.<br />
<br />
{{Note|PulseEffects new version ([[PipeWire#EasyEffects|EasyEffects]]) only supports Pipewire. You need to install the legacy version ({{AUR|pulseeffects-legacy}} or {{AUR|pulseeffects-legacy-git}}) to use it with PulseAudio.}}<br />
<br />
You may need to also install its optional dependency {{Pkg|lsp-plugins}} in order to get plugins to work. If PulseEffects plugins are greyed out after installing plugins, trying to start the daemon produces an error, or no devices are shown in the ''Settings > PulseAudio'' tab, consider clearing the cache as shown in [https://github.com/wwmm/easyeffects/issues/488#issuecomment-484101349].<br />
<br />
A collection of PulseEffects presets can be found in [https://github.com/wwmm/easyeffects/wiki/Community-presets community presets].<br />
<br />
=== Equalization ===<br />
<br />
If you want to use a different equalizer rather that the one integrated in [[#PulseEffects]], there are the following options.<br />
<br />
==== LADSPA module ====<br />
<br />
Install {{Pkg|pulseaudio-equalizer-ladspa}}, an equalizer based on LADSPA {{Pkg|swh-plugins}}. Launch {{ic|pulseaudio-equalizer-gtk}} GUI and tweak the parameters to match your expectations.<br />
<br />
==== Integrated module ====<br />
<br />
PulseAudio has an integrated 10-band equalizer system. In order to use it, install {{Pkg|pulseaudio-equalizer}} and read the following instructions.<br />
<br />
{{Warning|PulseAudio equalizer module is considered [https://lists.freedesktop.org/archives/pulseaudio-discuss/2014-March/020174.html unstable and might be removed from PulseAudio].}}<br />
<br />
Load the equalizer sink and dbus-protocol module<br />
<br />
$ pactl load-module module-equalizer-sink<br />
$ pactl load-module module-dbus-protocol<br />
<br />
To start the GUI, run {{ic|qpaeq}}.<br />
<br />
{{Note|If qpaeq has no effect, install {{pkg|pavucontrol}} and change "ALSA Playback on" to "FFT based equalizer on ..." while the media player is running.}}<br />
<br />
To load the equalizer and dbus module on every boot, create a ''.pa'' file in {{ic|/etc/pulse/default.pa.d/}} or edit {{ic|~/.config/pulse/default.pa}} and add the following lines:<br />
<br />
### Load the integrated PulseAudio equalizer and D-Bus module<br />
load-module module-equalizer-sink<br />
load-module module-dbus-protocol<br />
<br />
{{Note|The equalizer sink needs to be loaded after the master sink is already available.}}<br />
<br />
=== Dynamic Range Compression ===<br />
<br />
[[wikipedia:Dynamic_range_compression|Dynamic range compression]] can be done with [[#PulseEffects]]. Anyway PulseEffects might introduce much overhead and latency to audio stream, so if you only need a compression effect and a minor load on the system, other options are available using a [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index47h3 module-ladspa-sink].<br />
<br />
==== Steve Harris plugin ====<br />
<br />
Steve Harris LADSPA is a set of plugins containing various compression modules. Install {{Pkg|swh-plugins}} and edit the configuration as the following<br />
<br />
{{hc|~/.config/pulse/default.pa|2=<br />
.include /etc/pulse/default.pa<br />
<br />
set-default-sink your_card_sink_name<br />
<br />
load-module module-ladspa-sink sink_name=shw_sc4 sink_master=your_card_sink_name plugin=sc4_1882 label=sc4 control=,,,,,,,,<br />
set-default-sink shw_sc4<br />
}}<br />
<br />
You have to specify your card sink name, get it from {{ic|pacmd list-sinks}}. In order to apply the changes, stop and restart Pulseaudio. The above configuration has empty control options using the default values. <br />
<br />
To tweak the module with custom control parameters, fill them respecting the right order.<br />
<br />
{| class="wikitable"<br />
! Control option || Description<br />
|+<br />
| RMS/peak (0/1) || The blanace between the RMS and peak envelope followers. RMS is generally better for subtle, musical compression and peak is better for heavier, fast compression and percussion.<br />
|+<br />
| Attack time (ms) || The attack time in milliseconds.<br />
|+<br />
| Release time (ms) || The release time in milliseconds.<br />
|+<br />
| Threshold level (dB) || The point at which the compressor will start to kick in.<br />
|+<br />
| Ratio (1:n) || The gain reduction ratio used when the signal level exceeds the threshold. 1 means no compression; higher values stronger compression. <br />
|+<br />
| Knee radius (dB) || The distance from the threshold where the knee curve starts.<br />
|+<br />
| Makeup gain (dB) || Controls the gain of the makeup input signal in decibels.<br />
|+<br />
| Amplitude (dB) || The level of the input signal, in decibels.<br />
|+<br />
| Gain reduction (dB) || The degree of gain reduction applied to the input signal, in decibels.<br />
|}<br />
<br />
Other plugins can be found in [http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html Steve Harris' LADSPA Plugin Documentation].<br />
<br />
==== Calf plugin ====<br />
<br />
For a more professional compressor, you can use the one developed by [https://calf-studio-gear.org/ Calf Studio Gear]. Install {{AUR|calf-ladspa}} and edit the configuration as the following<br />
<br />
{{hc|~/.config/pulse/default.pa|2=<br />
.include /etc/pulse/default.pa<br />
<br />
set-default-sink your_card_sink_name<br />
<br />
load-module module-ladspa-sink sink_name=calf_comp_x2 sink_master=your_card_sink_name plugin=veal label=Compressor control=,,,,,,,,,,<br />
set-default-sink calf_comp_x2<br />
}}<br />
<br />
The plugin has 11 control options. If you want to insert custom values, read the following table and do not forget to specify them in the right order. <br />
<br />
{| class="wikitable"<br />
! Control option || Default || Min || Max || Type || Info<br />
|+<br />
| Bypass || 0 || 0 || 1 || Bool || <br />
|+<br />
| Level in || 1 || 0.015625 || 64 || Float db || <br />
|+<br />
| Threshold || 0.125 || 0.000976563 || 1 || Float dbFs || For example, to set -18 db, the right value is 10^(-18/20) = 0.158<br />
|+<br />
| Ratio || 2 || 1 || 20 || Float || <br />
|+<br />
| Attack || 20 || 0.01 || 2000 || Float ms || <br />
|+<br />
| Release || 250 || 0.01 || 2000 || Float ms || <br />
|+<br />
| Makeup || 1 || 1 || 64 || Float db || <br />
|+<br />
| Knee || 2.828427125 || 1 || 8 || Float db || <br />
|+<br />
| RMS/Peak || 0 || 0 || 1 || Bool || 0 = RMS; 1 = Peak<br />
|+<br />
| Stereo Link || 0 || 0 || 1 || Bool || 0 = Average; 1 = Max<br />
|+<br />
| Mix || 1 || 0 || 1 || Float || Percentage<br />
|+<br />
| colspan="6" | To understand the meaning of every single option, read the [https://calf-studio-gear.org/doc/Compressor.html Calf Compressor Documentation].<br />
|}<br />
<br />
=== Microphone echo/noise cancellation ===<br />
<br />
Arch does not load the PulseAudio echo-cancellation module by default, therefore, we have to add it in {{ic|/etc/pulse/default.pa.d/}}. First you can test if the module is present with {{ic|pacmd}} and entering {{ic|list-modules}}. If you cannot find a line showing {{ic|name: <module-echo-cancel>}} you have to create:<br />
<br />
{{hc|/etc/pulse/default.pa.d/noise-cancellation.pa|2=<br />
### Enable Echo/Noise-Cancellation<br />
load-module module-echo-cancel use_master_format=1 aec_method=webrtc aec_args="analog_gain_control=0\ digital_gain_control=1" source_name=echoCancel_source sink_name=echoCancel_sink<br />
set-default-source echoCancel_source<br />
set-default-sink echoCancel_sink<br />
}}<br />
<br />
then restart Pulseaudio:<br />
<br />
$ pulseaudio -k<br />
$ pulseaudio --start<br />
<br />
and check if the module is activated by starting {{ic|pavucontrol}}. Under {{ic|Recording}} the input device should show {{ic|Echo-Cancel Source Stream from"}}.<br />
<br />
Turning on {{ic|1=beamforming=1}} in the aec_args can also significantly reduce background noise if you have more than one microphone (which is common on many new laptops). However, beamforming requires specifying your {{ic|mic_geometry}} (see below).<br />
<br />
If you want existing streams to be automatically moved to the new sink and source, you have to load the [[Bluetooth headset#Setting up auto connection|module-switch-on-connect]] with {{ic|1=ignore_virtual=no}} before.<br />
<br />
{{Note|1=If you plug in a USB sound card or headset, or you have for example a 5.1 Speaker configuration and plug in a headset on your front audio connectors after you have loaded the {{ic|module-echo-cancel}}, you have to manually unload and load the {{ic|module-echo-cancel}} again, because unfortunately there is no way to tell the module that it should automatically switch to the new default 'source_master' and 'source_sink'. See [https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/196].}}<br />
<br />
==== Possible 'aec_args' for 'aec_method=webrtc' ====<br />
<br />
Here is a list of possible 'aec_args' for 'aec_method=webrtc' with their default values [https://github.com/pulseaudio/pulseaudio/blob/master/src/modules/echo-cancel/webrtc.cc][https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index45h3]:<br />
<br />
* {{ic|1=analog_gain_control=1}} - Analog AGC - 'Automatic Gain Control' done over changing the volume directly - Will most likely lead to [[PulseAudio/Troubleshooting#Microphone distorted due to automatic adjustment|distortions]].<br />
* {{ic|1=digital_gain_control=0}} - Digital AGC - 'Automatic Gain Control' done in post processing (higher CPU load).<br />
* {{ic|1=experimental_agc=0}} - Allow enabling of the webrtc experimental AGC mechanism.<br />
* {{ic|1=agc_start_volume=85}} - Initial volume when using AGC - Possible values 0-255 - A too low initial volume may prevent the AGC algorithm from ever raising the volume high enough [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/9.0/].<br />
* {{ic|1=high_pass_filter=1}} - ?<br />
* {{ic|1=noise_suppression=1}} - Noise suppression.<br />
* {{ic|1=voice_detection=1}} - VAD - Voice activity detection.<br />
* {{ic|1=extended_filter=0}} - The extended filter is more complex and less sensitive to incorrect delay reporting from the hardware than the regular filter. The extended filter mode is disabled by default, because it seemed produce worse results during double-talk [https://www.freedesktop.org/wiki/Software/PulseAudio/Notes/9.0/]. Enable this option if your microphone or speaker has a larger latency, for example, if you use a wireless microphone or some HDMI TVs as speaker.<br />
* {{ic|1=intelligibility_enhancer=0}} - Some bits for webrtc intelligibility enhancer.<br />
* {{ic|1=drift_compensation=0}} - Drift compensation to allow echo cancellation between different devices (such as speakers on your laptop and the microphone on your USB webcam). - only possible with "mobile=0".<br />
* {{ic|1=beamforming=0}} - This can significantly reduce background noise. See [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#index45h3][https://arunraghavan.net/2016/06/beamforming-in-pulseaudio/]<br />
** {{ic|1=mic_geometry=x1,y1,z1,x2,y2,z2}} - Only with "beamforming=1".<br />
** {{ic|1=target_direction=a,e,r}} - Only with "beamforming=1". Note: If the module does not want to load with this argument, set azimuth (a) to the desired value, but set elevation (e) and radius (r) to 0.<br />
* {{ic|1=mobile=0}} - ?<br />
** {{ic|1=routing_mode=speakerphone}} - Possible Values "quiet-earpiece-or-headset,earpiece,loud-earpiece,speakerphone,loud-speakerphone" - only valid with "mobile=1".<br />
** {{ic|1=comfort_noise=1}} - ? - only valid with "mobile=1".<br />
<br />
==== Disable audio post processing in certain applications ====<br />
<br />
If you are using the [[#Microphone echo/noise cancellation|module-echo-cancel]], you probably do not want other applications to do additional audio post processing. Here is a list for disabling audio post processing in following applications:<br />
<br />
* Mumble:<br />
*# Configure -> Settings -> Check 'Advanced' check box -> Audio Input<br />
*# Echo: Select 'Disabled'<br />
*# Noise Suppression: Set slider to 'Off'<br />
*# Max. Aplification: Set slider to '1.0'<br />
* TeamSpeak:<br />
*# Tools -> Options -> Capture<br />
*# Uncheck: 'Typing attenuation', 'Remove background noise', 'Echo cancellation' and 'Echo reduction (Ducking)'<br />
* Firefox: see [[Firefox tweaks#Disable WebRTC audio post processing]]<br />
* Steam:<br />
*# In window "Friends List" -> Manage friends list settings (gear symbol) -> VOICE -> Show Advanced Settings<br />
*# Set the following sliders to "OFF": "Echo cancellation", "Noise cancellation", "Automatic volume/gain control"<br />
* Skype:<br />
*# Tools -> Settings... -> Audio & Video -> Microphone -> Automatically adjust microphone settings -> off<br />
<br />
==== Script for reloading module-echo-cancel ====<br />
<br />
Since the module-echo-cancel is not always needed, or must be reloaded if the source_master or sink_master has changed, it is nice to have a easy way to load or reload the module-echo-cancel.<br />
<br />
[[Create]] the following script and make it [[executable]]:<br />
<br />
{{hc|echoCancelEnable.sh|<nowiki><br />
#!/bin/bash<br />
aecArgs="$*"<br />
# If no "aec_args" are passed on to the script, use this "aec_args" as default:<br />
[ -z "$aecArgs" ] && aecArgs="analog_gain_control=0 digital_gain_control=1"<br />
newSourceName="echoCancelSource"<br />
newSinkName="echoCancelSink"<br />
<br />
# "module-switch-on-connect" with "ignore_virtual=no" (needs PulseAudio 12 or higher) is needed to automatically move existing streams to a new (virtual) default source and sink.<br />
if ! pactl list modules short | grep "module-switch-on-connect.*ignore_virtual=no" >/dev/null 2>&1; then<br />
echo Load module \"module-switch-on-connect\" with \"ignore_virtual=no\"<br />
pactl unload-module module-switch-on-connect 2>/dev/null<br />
pactl load-module module-switch-on-connect ignore_virtual=no<br />
fi<br />
<br />
# Reload "module-echo-cancel"<br />
echo Reload \"module-echo-cancel\" with \"aec_args=$aecArgs\"<br />
pactl unload-module module-echo-cancel 2>/dev/null<br />
if pactl load-module module-echo-cancel use_master_format=1 aec_method=webrtc aec_args=\"$aecArgs\" source_name=$newSourceName sink_name=$newSinkName; then<br />
# Set a new default source and sink, if module-echo-cancel has loaded successfully.<br />
pacmd set-default-source $newSourceName<br />
pacmd set-default-sink $newSinkName<br />
fi<br />
</nowiki>}}<br />
<br />
To run the script easily from the graphical environment, you can create a [[desktop launcher]] for it.<br />
<br />
=== Recurrent neural network noise suppression (RNNoise) ===<br />
<br />
Installing the package {{AUR|noise-suppression-for-voice}} will allow real-time noise suppression based on RNNoise: Learning Noise Suppression [https://jmvalin.ca/demo/rnnoise/]. Configuration details can be found on the projects Github site [https://github.com/werman/noise-suppression-for-voice]. One can install Cadmus ({{AUR|cadmus-deb}} or {{AUR|cadmus-appimage}}) which is a GUI frontend for @werman's Pulse Audio real-time noise suppression plugin.<br />
<br />
Another alternative is {{AUR|noisetorch}} which is also build on top of RNNoise. There is not only input noise cancellation but also an output.<br />
<br />
== Applications ==<br />
<br />
=== QEMU ===<br />
<br />
Refer to [[QEMU#Host]] for a detailed guide on how to configure pulseaudio within [[QEMU]].<br />
<br />
=== AlsaMixer.app ===<br />
<br />
Make {{AUR|alsamixer.app}} dockapp for the {{AUR|windowmaker}} use pulseaudio, e.g.:<br />
<br />
$ AlsaMixer.app --device pulse<br />
<br />
Here is a two examples where the first one is for ALSA and the other one is for pulseaudio. You can run multiple instances of it. Use the {{ic|-w}} option to choose which of the control buttons to bind to the mouse wheel.<br />
<br />
# AlsaMixer.app -3 Mic -1 Master -2 PCM --card 0 -w 1<br />
# AlsaMixer.app --device pulse -1 Capture -2 Master -w 2<br />
<br />
{{Note|It can use only those output sinks that set as default.}}<br />
<br />
=== XMMS2 ===<br />
<br />
Make it switch to pulseaudio output:<br />
<br />
$ nyxmms2 server config output.plugin pulse<br />
<br />
and to alsa:<br />
<br />
$ nyxmms2 server config output.plugin alsa<br />
<br />
To make xmms2 use a different output sink, e.g.:<br />
<br />
$ nyxmms2 server config pulse.sink alsa_output.pci-0000_04_01.0.analog-stereo.monitor<br />
<br />
See also the official guide [https://xmms2.org/wiki/Using_the_application].<br />
<br />
=== KDE Plasma Workspaces and Qt4 ===<br />
<br />
PulseAudio will automatically be used by KDE/Qt4 applications. It is supported by default in the KDE sound mixer. For more information see the [https://www.freedesktop.org/wiki/Software/PulseAudio/Desktops/KDE/ KDE page in the PulseAudio wiki].<br />
<br />
One useful tidbit from that page is that {{ic|load-module module-device-manager}} should be loaded. This usually happens automatically at login through the script {{ic|/usr/bin/start-pulseaudio-x11}}; if you find that the module is not loaded automatically you can consider adding it manually to a configuration file in {{ic|/etc/pulse/default.pa.d/}}. See [[#Switch on connect]] for possible conflicts with the {{ic|module-switch-on-connect}}.<br />
<br />
If the phonon-gstreamer backend is used for [[Phonon]], GStreamer should also be configured as described in [[#GStreamer]].<br />
<br />
=== Audacious ===<br />
<br />
In order to use PulseAudio, set Edit → Preferences… → Devices → Playback → Device in Audacious to “default” or “pulse”. These devices are added to the drop-down list by {{Pkg|pulseaudio-alsa}}.<br />
<br />
=== Music Player Daemon (MPD) ===<br />
<br />
[https://mpd.wikia.com/wiki/PulseAudio Configure] [[MPD]] to use PulseAudio. See also [[MPD/Tips and Tricks#PulseAudio]].<br />
<br />
=== MPlayer ===<br />
<br />
[[MPlayer]] natively supports PulseAudio output with the {{ic|-ao pulse}} option. It can also be configured to default to PulseAudio output, in {{ic|~/.mplayer/config}} for per-user, or {{ic|/etc/mplayer/mplayer.conf}} for system-wide:<br />
<br />
{{hc|/etc/mplayer/mplayer.conf|2=<br />
ao=pulse<br />
}}<br />
<br />
=== mpv ===<br />
<br />
[[mpv]] supports PulseAudio same as written for [[#MPlayer]]. Configuration in {{ic|~/.config/mpv/mpv.conf}} per-user, or {{ic|/etc/mpv/mpv.conf}} system-wide.<br />
<br />
=== guvcview ===<br />
<br />
{{Pkg|guvcview}} when using the PulseAudio input from a [[Webcam]] may have the audio input suspended resulting in no audio being recorded. You can check this by executing:<br />
<br />
$ pactl list sources<br />
<br />
If the audio source is "suspended" then create the folowing ''.pa'' file:<br />
<br />
{{ic|/etc/pulse/default.pa.d/no-module-suspend-on-idle.pa|<br />
unload-module module-suspend-on-idle<br />
}}<br />
<br />
And then either restarting PulseAudio or your computer will only idle the input source instead of suspending it. guvcview will then correctly record audio from the device.<br />
<br />
== Networked audio ==<br />
<br />
{{Merge|PulseAudio/Examples#PulseAudio over network|No need for two separate sections.}}<br />
<br />
One of PulseAudio's unique features is its ability to stream audio from clients over TCP to a server running the PulseAudio daemon reliably within a LAN. Ensure that client and server systems agree on the time (i.e., use NTP), or audio streams may be choppy or may not work at all. For a more detailed guide visit the [https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Network/ Official PulseAudio Documentation]<br />
<br />
Enable the TCP module on the server(the computer that actually outputs sound), create the folowing ''.pa'' file:<br />
<br />
{{hc|/etc/pulse/default.pa.d/tcp.pa|<br />
load-module module-native-protocol-tcp<br />
}}<br />
<br />
Or you can use the {{ic|paprefs}} gui application (root is not required). Go to ''Network Server > Enable network access to local sound devices''.<br />
<br />
To make sure module-native-protocol-tcp is loaded on the server, you can use:<br />
<br />
$ pacmd list-modules | grep module-native-protocol-tcp<br />
<br />
It is a requirement that both the client and server share the same cookie. Ensure that the clients and server share the same cookie file found under {{ic|~/.config/pulse/cookie}}. It does not matter whose cookie file you use (the server or a client's), just that the server and client(s) share the same one.<br />
<br />
If it is undesirable to copy the cookie file from clients, anonymous clients can access the server by passing {{ic|auth-anonymous}} to {{ic|module-native-protocol-tcp}} on the server (again in {{ic|/etc/pulse/default.pa.d/}}):<br />
<br />
load-module module-native-protocol-tcp auth-anonymous=1<br />
<br />
It is also possible to authenticate based on client IP address:<br />
<br />
load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;192.168.0.0/24<br />
<br />
Change the LAN IP subnet to match that of those clients you wish to have access to the server.<br />
<br />
=== Starting system-wide on boot ===<br />
<br />
The pulseaudio daemon normally starts as a user service when a user logs in and attempts to play some sort of audio. For running a dedicated pulseaudio server accepting client connections over TCP, the daemon must be started on boot as a system service. To do this, create {{ic|pulseaudio.service}} in {{ic|/etc/systemd/system}} containing the following:<br />
<br />
[Unit]<br />
Description=Sound Service<br />
<br />
[Service]<br />
# Note that notify will only work if --daemonize=no<br />
Type=notify<br />
ExecStart=/usr/bin/pulseaudio --daemonize=no --exit-idle-time=-1 --disallow-exit=true<br />
Restart=always<br />
<br />
[Install]<br />
WantedBy=default.target<br />
<br />
Then enable {{ic|pulseaudio.service}} at the system level.<br />
<br />
# systemctl enable --now pulseaudio<br />
<br />
You will also need to disable the user-level pulseaudio service across the whole system:<br />
<br />
# systemctl --global mask pulseaudio.socket<br />
<br />
This is necessary even if you are accessing the system over SSH, to make sure the user-level pulseaudio service will never start.<br />
<br />
=== Selecting the Server ===<br />
<br />
For a single shell or command you can set the environment variable {{ic|$PULSE_SERVER}} to the host name or IP address of the desired PulseAudio server.<br />
<br />
$ env PULSE_SERVER=''server-hostname-or-ip'' mplayer test.mp3<br />
<br />
Alternatively you can create or modify {{ic|~/.pulse/client.conf}} or {{ic|/etc/pulse/client.conf}} to set a default-server persistently.<br />
<br />
default-server = ''server-hostname-or-ip''<br />
<br />
It is also possible to specify multiple servers separated by spaces which are subsequently tried by PulseAudio[https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/ServerStrings/]:<br />
<br />
default-server = ''server1'' ''backup''<br />
<br />
== Tips and tricks ==<br />
<br />
{{Merge|PulseAudio/Examples|Same topic.}}<br />
<br />
=== Keyboard volume control ===<br />
<br />
See [[Keyboard shortcuts#Xorg]] to bind the following commands to your volume keys: {{ic|XF86AudioRaiseVolume}}, {{ic|XF86AudioLowerVolume}} and {{ic|XF86AudioMute}}.<br />
<br />
First find out which sink corresponds to the audio output you would like to control.<br />
To list available sinks:<br />
<br />
$ pactl list sinks short<br />
<br />
Suppose sink 0 is to be used, to raise the volume:<br />
$ sh -c "pactl set-sink-mute 0 false ; pactl set-sink-volume 0 +5%"<br />
<br />
To lower the volume:<br />
<br />
$ sh -c "pactl set-sink-mute 0 false ; pactl set-sink-volume 0 -5%"<br />
<br />
To mute/unmute the volume:<br />
<br />
$ pactl set-sink-mute 0 toggle<br />
<br />
To mute/unmute the microphone:<br />
<br />
$ pactl set-source-mute 1 toggle<br />
<br />
{{Tip|<br />
* To have keyboard shortcuts operate always on the default sink, specify {{ic|@DEFAULT_SINK@}} as the sink number, for example {{ic|pactl set-sink-mute @DEFAULT_SINK@ toggle}}.<br />
* For more advanced control, such as limiting the maximum volume, consider using one of the [[#Console|console front-ends]].<br />
}}<br />
<br />
=== Play sound from a non-interactive shell (systemd service, cron) ===<br />
<br />
Set {{ic|XDG_RUNTIME_DIR}} before the command (replace {{ic|''user_id''}} with the ID of the user running PulseAudio):<br />
<br />
$ XDG_RUNTIME_DIR=/run/user/''user_id'' paplay /usr/share/sounds/freedesktop/stereo/complete.oga<br />
<br />
Or use {{ic|machinectl}}:<br />
<br />
# machinectl shell .host --uid=''user_id'' /usr/bin/paplay /usr/share/sounds/freedesktop/stereo/complete.oga<br />
<br />
=== X11 Bell Events ===<br />
<br />
To get pulseaudio to handle X11 bell events, run the following commands after the X11 session has been started:<br />
<br />
$ pactl upload-sample /usr/share/sounds/freedesktop/stereo/bell.oga bell-window-system<br />
$ pactl load-module module-x11-bell display=$DISPLAY<br />
<br />
Or use configuration files {{ic|/etc/pulse/default.pa.d/}} or {{ic|~/.config/pulse/default.pa}}:<br />
<br />
{{hc|~/.config/pulse/default.pa|2=<br />
.include /etc/pulse/default.pa<br />
<br />
# audible bell<br />
load-sample-lazy bell-window-system /usr/share/sounds/freedesktop/stereo/bell.oga<br />
load-module module-x11-bell<br />
}}<br />
<br />
To adjust the volume of the X11 bell, run the following command:<br />
<br />
$ xset b 100<br />
<br />
100 is a percentage. This requires the {{Pkg|xorg-xset}} package. See [[Autostarting]] for a way to run these commands automatically when the X11 session is started.<br />
<br />
=== Switch on connect ===<br />
<br />
This is a default enabled module used to switch the output sound to the newly connected device. For example, if you plug in a USB headset, the output will be switched to that. If you unplug it, the output will be set back to the last device. This used to be quite buggy but got a lot of attention in PulseAudio 8.0 and should work quite well now. <br />
<br />
{{Note|It does not work with some devices, see [[PulseAudio/Troubleshooting#ALSA channels mute when headphones are plugged/unplugged improperly]].}}<br />
<br />
=== Script for switching analog outputs ===<br />
<br />
Some sound cards present the option of multiple analog outputs, being switchable through using Pulseaudio profiles. But switching manually can become a chore, so you can use the following commands to switch it:<br />
<br />
$ pactl set-sink-port 'number of the card' 'port'<br />
<br />
This will set the default output to whatever port you chose.<br />
Example:<br />
<br />
$ pactl set-sink-port 0 "analog-output;output-speaker" <br />
<br />
The values can be easily obtained using:<br />
<br />
$ pactl list<br />
<br />
Current output can be obtained through:<br />
<br />
$ pactl list sinks | grep "active profile"| cut -d ' ' -f 3-<br />
<br />
This process can be automated through a simple script. This script then can be given a shortcut by the user:<br />
<br />
{{hc|~/pa.sh (or anything the user wants)|<nowiki><br />
#!/bin/bash<br />
# This script uses kdialog notification to warn the user of the currently swapped to profile. User could adapt it to their needs or change it.<br />
<br />
CURRENT_PROFILE=$(pactl list sinks | grep "active profile"| cut -d ' ' -f 3-)<br />
<br />
if [ "$CURRENT_PROFILE" = "analog-output;output-speaker" ] ; then<br />
pactl set-sink-port 0 "analog-output;output-headphones-1"<br />
kdialog --title "Pulseaudio" --passivepopup "Headphone" 2 & <br />
else <br />
pactl set-sink-port 0 "analog-output;output-speaker" <br />
kdialog --title "Pulseaudio" --passivepopup "Speaker" 2 &<br />
fi<br />
</nowiki>}}<br />
<br />
This script is intended to swap between two profiles. First checking the current profile then swapping it. Users are required to change the field 'active profile' according to the language pactl reports. Users might need to change the number of the card and the output to fit their machine.<br />
<br />
=== Disable muting media on entering voice call (module-role-cork) ===<br />
<br />
When entering a voice call (e.g. in Microsoft Teams, maybe others too) any media applications might be muted. To disable this behaviour you can simply disable this module in PulseAudio configuration:<br />
<br />
{{hc|/etc/pulse/default.pa.d/no-cork.pa|<br />
unload-module module-role-cork<br />
}}<br />
<br />
== Advanced configuration and use cases ==<br />
<br />
See [[PulseAudio/Examples]].<br />
<br />
== Troubleshooting ==<br />
<br />
See [[PulseAudio/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* [https://www.freedesktop.org/wiki/Software/PulseAudio/ PulseAudio official website], including documentation<br />
* [https://gavv.github.io/articles/pulseaudio-under-the-hood/ Pulseaudio under the hood]</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Unclutter&diff=558891Unclutter2018-12-11T14:32:54Z<p>Airblader: Update that unclutter is now unclutter-xfixes</p>
<hr />
<div>[[Category:X server]]<br />
[[ja:Unclutter]]<br />
Unclutter hides your X mouse cursor when you do not need it, to prevent it from getting in the way. You have only to move the mouse to restore the mouse cursor. Unclutter is very useful in tiling window managers where you do not need the mouse often.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|unclutter}} package.<br />
<br />
{{Note|Arch actually ships unclutter-xfixes instead of the original in this package.}}<br />
<br />
== Usage ==<br />
<br />
Use your ''.xinitrc'' file or WM/DE to start unclutter. For example, add the following to your ''.xinitrc'':<br />
<br />
unclutter &<br />
<br />
== Known bugs ==<br />
<br />
=== Misbehaviour of the mouse cursor ===<br />
<br />
If you experience issues when using unclutter in conjunction with a tiling window manager (such as [[xmonad]] or [[i3]]), install {{AUR|unclutter-xfixes-git}} instead or use the {{ic|-grab}} option:<br />
<br />
unclutter -grab &<br />
<br />
{{Note|The {{ic|-grab}} option breaks some screen locking applications such as ''slock'' and ''i3lock''.}}<br />
<br />
Unclutter could cause unusual mouse behaviour in some SDL Games. The mouse cursor might be reset to some positions in the screen because of<br />
this problem. The details can be found [https://bugs.launchpad.net/ubuntu/+source/unclutter/+bug/61105 here].<br />
<br />
There are two known workarounds for this. You can either add {{ic|SDL_VIDEO_X11_DGAMOUSE&#61;0}} to your environment variables which does not work for all games or run unclutter with<br />
{{ic|-grab}} option. However, it is important to note that the grab option may cause some applications such as gksu to not work properly.<br />
<br />
== Alternatives ==<br />
<br />
=== unclutter-xfixes ===<br />
<br />
Unclutter is a tool from the early 90s and has not been updated since. It works by creating fake windows or active pointer grabs, both of which often cause problems. By now, the X11 extensions Xinput2 and Xfixes have been released and are commonly found on most user systems. Using those, {{AUR|unclutter-xfixes-git}} can provide the cursor hiding functionality without interfering with any application.<br />
<br />
As of December 2018, community/unclutter will actually ship this rewrite instead of the original[https://github.com/Airblader/unclutter-xfixes/issues/33#issuecomment-446209712][https://git.archlinux.org/svntogit/community.git/commit/trunk?h=packages/unclutter&id=e652764bc5e55caefd3cd0df886554d3c76253ee].<br />
<br />
=== xbanish ===<br />
<br />
xbanish is another tool similar to unclutter, but works in a different way. Instead of using cursor movements, xbanish hides the cursor during typing. You can grab it on the AUR as {{AUR|xbanish}} or {{AUR|xbanish-git}}.<br />
<br />
== See also ==<br />
<br />
http://linuxappfinder.com/package/unclutter - Unclutter on Linux App Finder</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Unclutter&diff=444350Unclutter2016-08-02T21:45:13Z<p>Airblader: Clarified what xbanish does and removed the incorrect statement that it's a rewrite</p>
<hr />
<div>[[Category:X server]]<br />
[[ja:Unclutter]]<br />
Unclutter hides your X mouse cursor when you do not need it, to prevent it from getting in the way. You have only to move the mouse to restore the mouse cursor. Unclutter is very useful in tiling window managers where you do not need the mouse often.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|unclutter}} package.<br />
<br />
== Usage ==<br />
<br />
Use your ''.xinitrc'' file or WM/DE to start unclutter. For example, add the following to your ''.xinitrc'':<br />
<br />
unclutter &<br />
<br />
== Known bugs ==<br />
<br />
=== Misbehaviour of the mouse cursor ===<br />
<br />
If you experience issues when using unclutter in conjunction with a tiling window manager (such as [[xmonad]] or [[i3]]), install {{AUR|unclutter-xfixes-git}} instead or use the {{ic|-grab}} option:<br />
<br />
unclutter -grab &<br />
<br />
{{Note|The {{ic|-grab}} option breaks some screen locking applications such as ''slock'' and ''i3lock''.}}<br />
<br />
Unclutter could cause unusual mouse behaviour in some SDL Games. The mouse cursor might be reset to some positions in the screen because of<br />
this problem. The details can be found [https://bugs.launchpad.net/ubuntu/+source/unclutter/+bug/61105 here].<br />
<br />
There are two known workarounds for this. You can either add {{ic|SDL_VIDEO_X11_DGAMOUSE&#61;0}} to your environment variables which does not work for all games or run unclutter with<br />
{{ic|-grab}} option. However, it is important to note that the grab option may cause some applications such as gksu to not work properly.<br />
<br />
== Alternatives ==<br />
<br />
=== unclutter-xfixes ===<br />
<br />
Unclutter is a tool from the early 90s and has not been updated since. It works by creating fake windows or active pointer grabs, both of which often cause problems. By now, the X11 extensions Xinput2 and Xfixes have been released and are commonly found on most user systems. Using those, {{AUR|unclutter-xfixes-git}} can provide the cursor hiding functionality without interfering with any application.<br />
<br />
=== xbanish ===<br />
<br />
xbanish is another tool similar to unclutter, but works in a different way. Instead of using cursor movements, xbanish hides the cursor during typing. You can grab it on the AUR as {{AUR|xbanish}} or {{AUR|xbanish-git}}.<br />
<br />
== See also ==<br />
<br />
http://linuxappfinder.com/package/unclutter - Unclutter on Linux App Finder</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=432865Lenovo ThinkPad T460s2016-04-26T06:51:41Z<p>Airblader: Removed sections that are not at all specific to this model.</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Model Description ==<br />
<br />
Lenovo ThinkPad T460s aka model 20F9-CTO1WW<br />
<br />
=== Support ===<br />
<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration]] || {{Yes}}<br />
|-<br />
| [[ALSA]] || {{Y|no beep}}<br />
|-<br />
| [[TrackPoint]] || {{Y| with linux-4.5.1}}<br />
|-<br />
| [[Touchpad]] || {{Yes}}<br />
|-<br />
| [[Webcam]] || {{Yes}}<br />
|-<br />
| Fingerprint Sensor || {{No}}<br />
|-<br />
| Mobile Broadband || {{Yes}}<br />
|-<br />
| Bluetooth || {{Yes}}<br />
|-<br />
| Suspend/Resume || {{Y|kernel patch}}<br />
|-<br />
| Hibernate/Resume || {{Y|without charger}}<br />
|}<br />
<br />
== Troubleshooting ==<br />
<br />
{{Style|Please link to existing resources such as [[TrackPoint]] and [[ALSA]] rather than duplicate things here. See [[:Category:Laptops]].}}<br />
<br />
The {{AUR|linux-t460s}} package includes kernel patches that fix the mouse and suspend issues described below, which can be useful until {{Pkg|linux}} includes these patches. Alternatively, {{AUR|linux-git}} can be used.<br />
<br />
=== Touchpad/TrackPoint ===<br />
<br />
With older kernels than 4.5.1, there is a [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working. This bug was fixed in linux-4.5.1.<br />
<br />
=== Suspend / Resume ===<br />
<br />
Suspending the T460s by closing the lid when running on battery causes the machine to freeze up entirely. This can be worked around by setting the "intel_pstate=no_hwp" kernel parameter or by compiling the kernel with the patch attached to the [https://bugzilla.kernel.org/show_bug.cgi?id=113551 kernel bug] tracking this issue. Kernel 4.6.0 (available via e.g. {{AUR|linux-git}}) resolves this issue.<br />
<br />
=== Hibernate / Resume ===<br />
<br />
The kernel patch for fixing suspend resume (see above) causes hibernation resume to fail when on charger power. The workaround is to unplug the charger when resuming from hibernation.<br />
<br />
=== Fingerprint Sensor ===<br />
<br />
The fingerprint sensor built into the T460s is currently not supported by [[Fprint]].<br />
<br />
=== ALSA Beep ===<br />
<br />
There is no "beep" input to the snd_hda_intel device, so beeps generated by terminal emulators etc. are not played.<br />
As a workaround, PulseAudio can be configured to pick up X11 bell events, see [[PulseAudio#X11 Bell Events]].<br />
<br />
=== Function keys ===<br />
<br />
Fn+Esc to enable FnLk which will make your function keys work.<br />
<br />
=== Video Issues ===<br />
<br />
With newer kernels (>= 4.5), there seems to be video flickering, i.e. the screen occasionally goes black for what seems to be a single frame. See bug reports: [https://bugs.freedesktop.org/show_bug.cgi?id=95010] [https://bugs.freedesktop.org/show_bug.cgi?id=91393].<br />
<br />
This can be worked around by using the {{ic|i915.enable_rc6&#61;0}} kernel parameter [https://bugs.freedesktop.org/show_bug.cgi?id=95010] (cf. [[Intel graphics#Skylake Support]])<br />
<br />
== Youtube ==<br />
<br />
[https://www.youtube.com/watch?v=fnYZAr-BaK0&list=PLiKgVPlhUNuxgKwoVH4MMUy5MLqjAE2ux&index=3 Dual boot install with bootctl]</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=429282Lenovo ThinkPad T460s2016-04-02T11:38:29Z<p>Airblader: added suspend problems</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Model Description ==<br />
<br />
Lenovo ThinkPad T460s<br />
<br />
=== Support ===<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration]] || {{Y|Manual}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Y|Manual}}<br />
|-<br />
| Trackpad || {{Yes}}<br />
|-<br />
| [[Webcam]] || {{Yes}}<br />
|-<br />
| Fingerprint Sensor || {{No}}<br />
|-<br />
| Mobile Broadband || ?<br />
|-<br />
| Bluetooth || {{Yes}}<br />
|}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad ===<br />
<br />
There is an open [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working.<br />
<br />
=== Suspend / Resume ===<br />
<br />
Suspending the T460s by closing the lid when running on battery causes the machine to freeze up entirely. This can be worked around by setting the "intel_pstate=no_hwp" kernel parameter oder by compiling the kernel with the patch attached to the [https://bugzilla.kernel.org/show_bug.cgi?id=113551 kernel bug] tracking this issue.<br />
<br />
=== Fingerprint Sensor ===<br />
<br />
The fingerprint sensor built into the T460s is currently not supported by [[Fprint]].</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=428349Lenovo ThinkPad T460s2016-03-28T17:14:19Z<p>Airblader: clarified fingerprint sensor support</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Model Description ==<br />
<br />
Lenovo ThinkPad T460s<br />
<br />
=== Support ===<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration]] || {{Y|Manual}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Y|Manual}}<br />
|-<br />
| Trackpad || {{Yes}}<br />
|-<br />
| [[Webcam]] || {{Yes}}<br />
|-<br />
| Fingerprint Sensor || {{No}}<br />
|-<br />
| Mobile Broadband || ?<br />
|-<br />
| Bluetooth || ?<br />
|}<br />
<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad ===<br />
<br />
There is an open [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working.<br />
<br />
=== Fingerprint Sensor ===<br />
<br />
The fingerprint sensor built into the T460s is currently not supported by [[Fprint]].</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=428348Lenovo ThinkPad T460s2016-03-28T17:08:59Z<p>Airblader: fixed markup</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Model Description ==<br />
<br />
Lenovo ThinkPad T460s<br />
<br />
=== Support ===<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration]] || {{Y|Manual}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Y|Manual}}<br />
|-<br />
| Trackpad || {{Yes}}<br />
|-<br />
| [[Webcam]] || {{Yes}}<br />
|-<br />
| Fingerprint Sensor || ?<br />
|-<br />
| Mobile Broadband || ?<br />
|-<br />
| Bluetooth || ?<br />
|}<br />
<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad ===<br />
<br />
There is an open [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working.</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=428347Lenovo ThinkPad T460s2016-03-28T17:08:44Z<p>Airblader: added support table</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Model Description<br />
<br />
Lenovo ThinkPad T460s<br />
<br />
=== Support ===<br />
<br />
{| class="wikitable"<br />
| '''Device''' || '''Working'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}}<br />
|-<br />
| [[Wireless network configuration]] || {{Y|Manual}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Y|Manual}}<br />
|-<br />
| Trackpad || {{Yes}}<br />
|-<br />
| [[Webcam]] || {{Yes}}<br />
|-<br />
| Fingerprint Sensor || ?<br />
|-<br />
| Mobile Broadband || ?<br />
|-<br />
| Bluetooth || ?<br />
|}<br />
<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad ===<br />
<br />
There is an open [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working.</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T460s&diff=425290Lenovo ThinkPad T460s2016-03-12T06:09:58Z<p>Airblader: Link kernel bug</p>
<hr />
<div>[[Category:Lenovo]]<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T460s laptop.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Touchpad ===<br />
<br />
There is an open [https://bugzilla.kernel.org/show_bug.cgi?id=114321 kernel bug] which causes the physical mouse button (belonging to the TrackPoint) to report release events immediately even when pressing and holding the button. This prevents drag and drop and similar actions from working.</div>Airbladerhttps://wiki.archlinux.org/index.php?title=I3&diff=422862I32016-02-27T20:23:27Z<p>Airblader: </p>
<hr />
<div>{{DISPLAYTITLE:i3}}<br />
[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:i3]]<br />
[[ko:I3]]<br />
[[ru:I3]]<br />
[[zh-CN:I3]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Clipboard}}<br />
{{Related|Autostarting#Graphical}}<br />
{{Related articles end}}<br />
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.<br />
<br />
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.<br />
<br />
Additional packages are available in the [[Arch User Repository]]. See the section [[#Patches]] for examples.<br />
<br />
=== Display manager ===<br />
<br />
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].<br />
<br />
=== xinitrc ===<br />
<br />
Edit [[Xinitrc]], and add:<br />
<br />
exec i3<br />
<br />
To log the output from i3, add this line instead:<br />
<br />
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1<br />
<br />
If you have trouble mapping keys (e.g. {{ic|;}} as semicolon), use {{Pkg|xorg-xev}} or see [[Extra keyboard keys]].<br />
<br />
$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'<br />
<br />
== Usage ==<br />
<br />
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].<br />
<br />
=== Application launcher ===<br />
<br />
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}. As an alternative, one can use {{AUR|dmenu2}} from the AUR which has many more features including transparency and support for xft fonts.<br />
<br />
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used; it is a near-drop-in replacement for ''i3-dmenu-desktop'', but much faster [https://github.com/enkore/j4-dmenu-desktop/blob/master/README.md].<br />
<br />
=== Keybindings ===<br />
<br />
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.<br />
<br />
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [http://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.<br />
<br />
=== Containers ===<br />
<br />
{{Expansion|The User's guide explains basic use of containers, yet is not sufficiently clear to allow more advanced use cases. It also does not mention ''focus child'' as it does ''focus parent''. See also: [https://faq.i3wm.org/question/222/how-to-get-rid-of-another-container/], [https://github.com/i3/i3/issues/1326]}}<br />
<br />
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
== Configuration ==<br />
<br />
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}} (contrary to ''i3-config-wizard'', which creates {{ic|~/.i3/config}}).<br />
<br />
=== Configuration wizard and alternative keyboard layouts ===<br />
<br />
When ''i3'' is first started, it offers to run the configuration wizard ''i3-config-wizard''. This tool creates {{ic|~/.i3/config}} by rewriting a template configuration file in {{ic|/etc/i3/config.keycodes}}. It makes two kinds of modifications to the default template: <br />
<br />
# It asks the user to choose a default modifier key, which it adds to the template as a single line, like {{ic|set $mod Mod1}}; and <br />
# it replaces all ''bindcode'' lines with ''bindsym'' lines corresponding to the user's current keyboard layout.<br />
<br />
Part 2 is designed to ensure that the four navigation shortcuts, {{ic|j}}, {{ic|k}}, {{ic|l}} and "semicolon" on a Qwerty keyboard, will be mapped to keysyms which have the same location, e.g. {{ic|h}}, {{ic|t}}, {{ic|n}}, {{ic|s}} on a Dvorak keyboard. The side-effect of this magic is that up to fifteen other keysyms may be remapped, often with confusing results - so that, for a Dvorak user, "restart" is bound to {{ic|$mod1+p}} instead of {{ic|$mod1+r}}, "split horizontally" is bound to {{ic|$mod1+d}} instead of {{ic|$mod1+h}}, and so on.<br />
<br />
Therefore, users of alternate keyboard layouts who want key bindings with easy mnemonics, and which match the bindings given in tutorials, may prefer to just copy {{ic|/etc/i3/config}} into {{ic|~/.config/i3/config}} (or {{ic|~/.i3/config}}) and start by editing that file, rather than using the config wizard.<br />
<br />
Note that a keycode-based configuration is also possible, e.g. for users who often switch between keyboard layouts, but want the i3 bindings to stay the same.<br />
<br />
=== Colorschemes ===<br />
<br />
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.<br />
<br />
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}{{Broken package link|{{aur-mirror|nodejs-i3-style}}}}}}<br />
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}<br />
<br />
=== i3bar ===<br />
<br />
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
output LVDS1<br />
status_command i3status<br />
position top<br />
mode hide<br />
workspace_buttons yes<br />
tray_output none<br />
<br />
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1<br />
<br />
colors {<br />
background #000000<br />
statusline #ffffff<br />
<br />
focused_workspace #ffffff #285577<br />
active_workspace #ffffff #333333<br />
inactive_workspace #888888 #222222<br />
urgent_workspace #ffffff #900000<br />
}<br />
}<br />
}}<br />
<br />
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<br />
<br />
{{Accuracy|i3 is [[Wikipedia:Extended_Window_Manager_Hints|NETWM]] compliant, so workspace management from external panels should usally work. See also [http://i3wm.org/docs/wsbar.html]}}<br />
<br />
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.<br />
<br />
For the [[Xfce#Panel|XFCE panel]], add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
{{Note|Panel features that are specific to the [[Desktop environment]] (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.}}<br />
<br />
i3bar can be disabled by commenting out the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}} or using: <br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
<br />
This way you can show or hide bar as you want.<br />
<br />
=== i3status ===<br />
<br />
Copy over the default configuration files to the home directory:<br />
<br />
$ cp /etc/i3status.conf ~/.config/i3status/config<br />
<br />
Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See {{ic|man i3status}} for details.<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |https://github.com/brndnmtthws/conky|{{Pkg|conky}}}}<br />
* {{App|[[i3blocks]]|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}<br />
* {{App|i3phtatus|An easily extensible i3status replacement meant for i3bar, written in PHP.|https://github.com/mwgg/i3phtatus}}<br />
* {{App|i3-phpbar|Same replacement for i3bar, written in PHP.|https://github.com/johnynsk/i3-phpbar}}<br />
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}<br />
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}<br />
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by {{Aur|j4status-plugins-git}}.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<br />
* {{App|[[h2status]]|Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.|[[H2status]]|{{Aur|h2status}}{{Broken package link|{{aur-mirror|h2status}}}}}}<br />
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}<br />
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|http://kageurufu.net/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
<br />
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:<br />
{{hc|~/.config/i3/config|2=<br />
bar {<br />
...<br />
font pango:DejaVu Sans Mono, Icons 8<br />
...<br />
}<br />
}}<br />
<br />
In accordance with [https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string pango syntax], font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.<br />
<br />
Add icons to the format strings in {{ic|~/.config/i3status/config}} using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):<br />
<br />
{{Merge|Internationalization|Should be described in one place; see also [[ArchWiki:Requests#Input methods]].}}<br />
<br />
* in various gui text editors (e.g. [[gedit]], Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): {{ic|ctrl+shift+u}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Emacs]]: {{ic|ctrl+x}}, {{ic|8}}, {{ic|Enter}}, {{ic|f004}}, {{ic|Enter}}<br />
* in [[Vim]] (while in insert mode): {{ic|Ctrl+v}}, {{ic|uf004}}<br />
* in [[urxvt]]: while holding {{ic|Ctrl+Shift}}, type {{ic|f004}}<br />
<br />
=== Terminal emulator ===<br />
<br />
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.<br />
<br />
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:<br />
<br />
bindsym $mod+Return exec i3-sensible-terminal<br />
<br />
Alternatively, [[Environment_variable#Per_user|locally define]] the {{ic|$TERMINAL}} variable:<br />
<br />
$ export TERMINAL=''yourterminal''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Advanced window navigation ===<br />
<br />
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].<br />
<br />
=== Jump to open window ===<br />
<br />
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}<br />
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}<br />
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}<br />
*{{App|[[rofi]]|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Pkg|rofi}}}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]<br />
<br />
bindsym $mod+x [urgent=latest] focus<br />
<br />
=== Save and restore the window layout ===<br />
<br />
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].<br />
<br />
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}<br />
<br />
==== Save the current window layout of a single workspace ====<br />
<br />
To save the current window layout, follow these steps:<br />
<br />
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.<br />
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}<br />
<br />
==== Restore the window layout of the workspace ====<br />
<br />
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.<br />
<br />
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:<br />
<br />
* The starting lines:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
}}<br />
<br />
where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.<br />
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.<br />
<br />
For example, if the saved layout contained three {{ic|uxterm}} windows:<br />
<br />
{{hc|head=~/load_layout.sh|output=<br />
#!/bin/bash<br />
<br />
# First we append the saved layout of worspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"<br />
<br />
# And finally we fill the containers with the programs they had<br />
(uxterm &)<br />
(uxterm &)<br />
(uxterm &)<br />
}}<br />
<br />
Then set the file as executable:<br />
<br />
chmod u+x ~/load_layout.sh<br />
<br />
And finally, the layout of worskpace N can be loaded onto to workspace M by running:<br />
<br />
~/load_layout.sh<br />
<br />
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}<br />
<br />
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.<br />
<br />
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again. <br />
<br />
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.<br />
<br />
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}<br />
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}<br />
<br />
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.<br />
<br />
=== Screensaver and power management ===<br />
<br />
With [[Power management#xss-lock]] you can register a screenlocker for your i3 session.<br />
<br />
Alternatively, ''xautolock'' can lock the screen after awakening from sleep or hibernation with the {{ic|-lockaftersleep}} option. The {{ic|-time}} option locks the screen after a given time period.<br />
<br />
xautolock -time 10 -locker "i3lock -i 'background_image.png'" -lockaftersleep &<br />
<br />
See also [[DPMS]].<br />
<br />
=== Shutdown, reboot, lock screen ===<br />
<br />
Key combinations for shutdown, reboot and screenlock can be added to {{ic|~/.config/i3/config}}. The below example assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.<br />
<br />
{{bc|<br />
set $Locker i3lock && sleep 1<br />
<br />
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown<br />
mode "$mode_system" {<br />
bindsym l exec --no-startup-id $Locker, mode "default"<br />
bindsym e exec --no-startup-id i3-msg exit, mode "default"<br />
bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"<br />
bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"<br />
bindsym r exec --no-startup-id systemctl reboot, mode "default"<br />
bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default" <br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
<br />
bindsym $mod+Pause mode "$mode_system"<br />
}}<br />
<br />
Once completed, you will be presented with a prompt whenever you press {{ic|$mod+pause}}. For more complex behaviour, use a separate script, and refer to it in the mode. [https://gist.github.com/anonymous/c8cd0a59bf4acb273068]<br />
<br />
{{Note|1=<br><br />
* {{ic|sleep 1}} adds a small delay to prevent possible race conditions with suspend [https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348]<br />
* The {{ic|-i}} argument for {{ic|systemctl poweroff}} causes a shutdown even if other users are logged-in (this requires {{Pkg|polkit}}), or when ''logind'' (wrongly) assumes so. [https://bugs.freedesktop.org/show_bug.cgi?id=62676]<br />
}}<br />
<br />
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].<br />
<br />
=== Tabbed or stacked web-browsing ===<br />
<br />
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.<br />
<br />
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}<br />
<br />
for_window [class="Uzbl-core"] focus child, layout stacking, focus<br />
<br />
This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.<br />
<br />
If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use<br />
<br />
for_window [class="Uzbl-core"] focus child, layout tabbed, focus<br />
<br />
=== Workspace variables ===<br />
<br />
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example [https://github.com/dkeg/bloat2.0/blob/master/i3config#L55]:<br />
<br />
set $WS1 term<br />
set $WS2 web<br />
set $WS3 misc<br />
set $WS4 media<br />
set $WS5 code<br />
<br />
Then replace workspace names with their matching variables:<br />
<br />
bindsym $mod+1 workspace $WS1<br />
...<br />
bindsym $mod+Shift+1 move container to workspace $WS1<br />
<br />
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.<br />
<br />
=== Correct handling of floating dialogs ===<br />
<br />
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}} (using [http://www.pcre.org/ pcre] syntax):<br />
<br />
for_window [window_role="pop-up"] floating enable<br />
for_window [window_role="task_dialog"] floating enable<br />
<br />
You can also use title rules and regular expressions:<br />
<br />
for_window [title="Preferences$"] floating enable<br />
<br />
or {{ic|WM_CLASS}}:<br />
<br />
for_window [class="(?i)mplayer"] floating enable<br />
<br />
=== Network Download/Upload speed on statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,<br />
<br />
* rename both network cards according to your system (use {{ic|ip addr}})<br />
* find them on {{ic|/sys/devices}} then replace them appropriately:<br />
$ find /sys/devices -name ''network_interface''<br />
<br />
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}<br />
<br />
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.<br />
<br />
== Patches ==<br />
<br />
Packages with patches not merged upstream are available in the [[AUR]]:<br />
<br />
* {{App|i3bar-icons-git|Display XBM icons in i3bar|https://github.com/ashinkarov/i3-extras|{{AUR|i3bar-icons-git}}{{Broken package link|{{aur-mirror|i3bar-icons-git}}}}}}<br />
* {{App|i3-smart-border|Smart borders|https://github.com/ashinkarov/i3-extras|{{AUR|i3-smart-border}}{{Broken package link|{{aur-mirror|i3-smart-border}}}}}}<br />
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== General ===<br />
<br />
In many cases, bugs are fixed in the development versions {{AUR|i3-git}} and {{AUR|i3status-git}}, and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] See also [[Debug - Getting Traces#General]].<br />
<br />
=== Buttons in the i3 message bar do not work ===<br />
<br />
Buttons such as "Edit config" in {{ic|i3-nagbar}} call {{ic|i3-sensible-terminal}}, so make sure your [[#Terminal_emulator|Terminal emulator]] is recognized by i3.<br />
<br />
=== Faulty line wraps in tiled terminals ===<br />
<br />
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.<br />
<br />
=== Mouse cursor remains in waiting mode ===<br />
<br />
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.<br />
<br />
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:<br />
exec --no-startup-id ~/script<br />
bindsym $mod+d exec --no-startup-id dmenu_run<br />
<br />
To disable this animation globally, see [[Cursor themes#Create links to missing cursors]].<br />
<br />
=== Unresponsive key bindings ===<br />
<br />
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument [http://i3wm.org/docs/userguide.html#keybindings]:<br />
<br />
bindsym --release Print exec --no-startup-id scrot<br />
bindsym --release Shift+Print exec --no-startup-id scrot -s<br />
<br />
=== Tearing ===<br />
<br />
i3 does [https://github.com/i3/i3/issues/661 not properly implement double buffering] hence tearing or flickering may occur. To prevent this, install and configure [[compton]]. [https://faq.i3wm.org/question/3279/do-i-need-a-composite-manager-compton/?answer=3282#post-id-3282]<br />
<br />
=== Tray icons not visible ===<br />
<br />
The default {{ic|tray_output primary}} directive may require setting a primary output with ''xrandr'', specifying the output explicitly or simply removing this directive. [https://github.com/i3/i3/issues/1144] See [[Xrandr]] for details. The default configuration created by i3-config-wizard will no longer add this directive to the configuration with i3 4.12.<br />
<br />
== See also ==<br />
<br />
* [http://i3wm.org Official website]<br />
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]<br />
* [http://code.stapelberg.de/git/i3 i3 Source code]<br />
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches<br />
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions<br />
* [https://github.com/veelenga/i3ipc-ruby i3ipc-ruby] - An improved library for i3 extensions in Ruby<br />
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3<br />
<br />
'''Arch Linux Forums'''<br />
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3<br />
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]<br />
<br />
'''Screencasts'''<br />
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Rxvt-unicode&diff=420731Rxvt-unicode2016-02-14T18:37:33Z<p>Airblader: Remove dots which are unnecessary acording to the resource manager spec</p>
<hr />
<div>{{DISPLAYTITLE:rxvt-unicode}}<br />
[[Category:Terminal emulators]]<br />
[[de:urxvt]]<br />
[[es:Rxvt-unicode]]<br />
[[fr:urxvt]]<br />
[[ja:Rxvt-unicode]]<br />
[[ru:Rxvt-unicode]]<br />
[[sr:Rxvt-unicode]]<br />
[http://software.schmorp.de/pkg/rxvt-unicode.html rxvt-unicode] is a highly customizable [[Wikipedia:Terminal emulator|terminal emulator]] forked from [[Wikipedia:Rxvt|rxvt]]. Commonly known as {{Ic|urxvt}}, rxvt-unicode can be [[daemon]]ized to run clients within a single [[Wikipedia:Process (computing)|process]] in order to minimize the use of system resources. Developed by Marc Lehmann, some of the more outstanding features of rxvt-unicode include international language support through [[Wikipedia:Unicode|Unicode]], the ability to display multiple font types and support for [[Wikipedia:Perl|Perl]] extensions.<br />
<br />
== Installation ==<br />
<br />
{{Pkg|rxvt-unicode}} is available in the [[official repositories]] and includes 256 color support.<br />
<br />
{{AUR|rxvt-unicode-patched}} is available in the [[AUR]] and includes a fix for the font width bug.<br />
<br />
== Configuration ==<br />
<br />
See the [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod rxvt-unicode reference page] for the complete list of available setting and values.<br />
<br />
=== Creating ~/.Xresources ===<br />
<br />
The look, feel, and function of rxvt-unicode is controlled by command-line arguments and/or [[X resources]]. X resources can be set using {{ic|~/.Xresources}} and ''xrdb'' ({{Pkg|xorg-xrdb}}), see the [[X resources]] article for details.<br />
<br />
Append commented list of all ''rxvt'' resources to your {{ic|~/.Xresources}} file:<br />
<br />
urxvt --help 2>&1| sed -n '/: /s/^ */! URxvt*/gp' >> ~/.Xresources<br />
<br />
Or for a commented list + helpful descriptions:<br />
<br />
{{bc|<nowiki>TERM=rxvt-unicode-256color command man -Pcat urxvt | sed -n '/depth: b/,/^BA/p'|sed '$d'|sed '/^ [a-z]/s/^ */^/g'|sed -e :a -e 'N;s/\n/@@/g;ta;P;D'|sed 's,\^\([^@]\+\)@*[\t ]*\([^\^]\+\),! \2\n! URxvt*\1\n\n,g'|sed 's,@@\( \+\),\n\1,g'|sed 's,@*$,,g'|sed '/^[^!]/d'|tr -d "'\`" >> ~/.Xresources</nowiki>}}<br />
<br />
{{Note|Command-line arguments override, and take precedence over resource settings}}<br />
<br />
=== True transparency ===<br />
<br />
To use true transparency, you need to be using a [[window manager]] that supports compositing or a separate compositor.<br />
<br />
From the command-line:<br />
<br />
$ urxvt -depth 32 -bg rgba:3f00/3f00/3f00/dddd<br />
<br />
Using the configuration file:<br />
<br />
{{hc|~/.Xresources|<br />
URxvt.depth: 32<br />
URxvt.background: rgba:1111/1111/1111/dddd<br />
}}<br />
<br />
or<br />
<br />
{{hc|~/.Xresources|<br />
URxvt.depth: 32<br />
URxvt.background: [95]#000000<br />
}}<br />
<br />
where '95' is the opacity level in percentage and '#000000' is the background color.<br />
<br />
To use a color i.e. #302351 with the rgba:rrrr/gggg/bbbb/aaaa syntax it would be rgba:3000/2300/5100/ee00. "ee00" (the alpha value) to make it nicely transparent.<br />
<br />
{{Note|To make these settings universal for all forms of URxvt, you may add a wildcard. For example, {{ic|URxvt.depth}} would become {{ic|URxvt*depth}}.}}<br />
<br />
=== Native transparency ===<br />
<br />
If there is no need for true transparency, or if compositing uses too many resources on your system, you can get transparency working in the following way:<br />
<br />
{{hc|~/.Xresources|<nowiki><br />
! Xresources file<br />
<br />
URxvt*inheritPixmap: true<br />
URxvt*transparent: true<br />
! URxvt*shading: 0 to 99 darkens, 101 to 200 lightens<br />
URxvt*shading: 110<br />
</nowiki>}}<br />
<br />
Using the URxvt*background setting exemplified above instead of URxvt*shading will also work.<br />
<br />
{{Note|Avoid using shading if you have a {{ic|URxvt.tintColor}} set. Use a different {{ic|tintColor}} instead.}}<br />
<br />
=== Scrollbar ===<br />
<br />
The look of the scrollbar can be chosen through this entry in {{ic|~/.Xresources}}:<br />
<br />
! scrollbar style - rxvt (default), plain (most compact), next, or xterm<br />
URxvt.scrollstyle: rxvt<br />
<br />
The scrollbar can also be completely deactivated like so:<br />
<br />
URxvt.scrollBar: false<br />
<br />
=== Scrollback position ===<br />
<br />
By default, when shell output appears the scrollback view will automatically jump to the bottom of the buffer to display new output. If in cases where you want to see previous output (e.g., compiler messages), set the following options in {{ic|~/.Xresources}}:<br />
<br />
! do not scroll with output<br />
URxvt*scrollTtyOutput: false<br />
<br />
! scroll in relation to buffer (with mouse scroll or Shift+Page Up)<br />
URxvt*scrollWithBuffer: true<br />
<br />
! scroll back to the bottom on keypress<br />
URxvt*scrollTtyKeypress: true<br />
<br />
=== Scrollback buffer in secondary screen ===<br />
<br />
When you scroll a pager in a ''secondary screen''(e.g. {{ic|less}} without the {{ic|'''-X'''}} option), it may be a good idea to disable the scrollback buffer to be able to scroll in the pager ''itself'', instead of the terminal's buffer: this is default and unchangeable behaviour in konsole and vte-based terminals.<br />
In urxvt, to disable the scrollback buffer for the ''secondary screen'':<br />
URxvt.secondaryScreen: 1<br />
URxvt.secondaryScroll: 0<br />
<br />
The above configuration works as expected except when scrolling with a mouse wheel. When you scroll a pager in the ''secondary screen'' with the mouse wheel - and there has been something in the scrollback buffer, instead of the pager itself - the scrollback buffer will be scrolled by the mouse wheel. To solve this issue, it is necessary to introduce a new option into rxvt-unicode[https://bbs.archlinux.org/viewtopic.php?id=132150]. A patched rxvt-unicode is available in AUR as {{aur|rxvt-unicode-better-wheel-scrolling}}. After installing it, add the following to the configuration file:<br />
URxvt.secondaryWheel: 1<br />
<br />
{{note|Please do not use this option with the [[#Scrollwheel support|vtwheel]] perl extension, it will mess up.}}<br />
<br />
=== Font declaration methods ===<br />
<br />
URxvt.font: 9x15<br />
is the same as:<br />
URxvt.font: -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso8859-1<br />
<br />
And, for the same font in bold:<br />
URxvt.font: 9x15bold<br />
is the same as:<br />
URxvt.font: -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-1<br />
<br />
The complete list of short names for X core fonts can be found in {{ic|/usr/share/fonts/misc/fonts.alias}} (there is also some fonts.alias files in some of the other subdirectories of {{ic|/usr/share/fonts/}}, but as they are packaged separately from the actual fonts, they may list fonts you do not actually have installed). It is worth noting that these short aliases select for ISO-8859-1 versions of the fonts rather than ISO-10646-1 (Unicode) versions, and 75 DPI rather than 100 DPI versions, so you are probably better off avoiding them and choosing fonts by their full long names instead.<br />
<br />
{{Note|The above paragraph is only for bitmap fonts. Other fonts can be used through Xft using the following format:}}<br />
URxvt.font: xft:monaco:size=10<br />
<br />
Or<br />
URxvt.font: xft:monaco:bold:size=10<br />
<br />
{{Note|<br />
* If there is a hyphen(-) in an Xft font name, it must be escaped with backslash(\) twice. It's different from the usage of urxvt -fn option and the result that fc-list returns, where backslash present only once<br />
* You will see a new font only after restart X}}<br />
<br />
A nice method for testing out fonts in a live terminal before committing to the config is by printing escape codes in the terminal, for example:<br />
<br />
$ printf '\e]710;%s\007' "xft:Terminus:pixelsize=12"<br />
<br />
=== Set icon ===<br />
<br />
{{Note|Because of a bug report{{Bug|34862}} complaining that the rxvt-unicode package had too many dependencies, you must now install the AUR package {{AUR|rxvt-unicode-pixbuf}} in order to use the icon option.}}<br />
<br />
By default URxvt does not feature a taskbar icon. However, this can be easily changed by adding the following line to {{ic|~/.Xresources}} and pointing to the desired icon:<br />
<br />
URxvt.iconFile: /usr/share/icons/Clarity/scalable/apps/terminal.svg<br />
<br />
=== Set as login shell ===<br />
<br />
This will cause the shell to be started as a login shell, like the option {{ic|-ls}}.<br />
URxvt*loginShell: true<br />
<br />
=== Use urxvt as application launcher ===<br />
<br />
urxvt can be used as a lightweight alternative to application launchers such as {{pkg|gmrun}}. Run urxvt with the following configuration to imitate look and behaviour of an application launcher or assign the command to a custom alias:<br />
<br />
$ urxvt -geometry 80x3 -name 'bashrun' -e sh -c "/bin/bash -i -t"<br />
<br />
=== Font spacing ===<br />
<br />
By default the distance between characters can feel too wide. It's controlled by this entry:<br />
<br />
{{hc|~/.Xresources|<nowiki><br />
URxvt.letterSpace: -1<br />
</nowiki>}}<br />
<br />
Here {{ic|-1}} decreases the spacing by one pixel, but can be adjusted as needed.<br />
<br />
== Perl extensions ==<br />
<br />
{{Style|Bias towards url-select while matcher and url-select are mostly equivalent, as well as man page duplication}}<br />
<br />
We can enable URxvt perl extensions by including the following line:<br />
<br />
URxvt.perl-ext-common: extension_name_1,extension_name_2,...<br />
<br />
Please take note that there '''should not''' be any spacing between extension names.<br />
<br />
=== Clickable URLs ===<br />
<br />
You can make URLs in the terminal clickable using the matcher extension. For example, to open links in [[Firefox]] add the following to {{ic|.Xresources}}:<br />
<br />
URxvt.perl-ext-common: default,matcher<br />
URxvt.url-launcher: /usr/bin/firefox<br />
URxvt.matcher.button: 1<br />
<br />
Since rxvt-unicode 9.14, it's also possible to use matcher to open and list recent (currently limited to 10) URLs via keyboard:<br />
<br />
URxvt.keysym.C-Delete: perl:matcher:last<br />
URxvt.keysym.M-Delete: perl:matcher:list<br />
<br />
Matching links can be colored with a chosen foreground or background [[#Colors|color]], for example blue:<br />
<br />
URxvt.matcher.rend.0: Uline Bold fg5<br />
<br />
Alternatively, use {{ic|colorUL}} for a #RRGGBB color. This will however color all underlined text, instead of only link matches:<br />
<br />
URxvt.colorUL: #4682B4<br />
<br />
=== Yankable URLs (no mouse) ===<br />
In addition, you can select and open URLs in your web browser without using the mouse.<br />
Install the {{Pkg|urxvt-perls}} package from the [[official repositories]] and adjust your {{ic|.Xresources}} as necessary. An example is shown below:<br />
URxvt.perl-ext: default,url-select<br />
URxvt.keysym.M-u: perl:url-select:select_next<br />
URxvt.url-select.launcher: /usr/bin/xdg-open<br />
URxvt.url-select.underline: true<br />
<br />
{{Note|This extension replaces the Clickable URLs extension mentioned above, so {{Ic|matcher}} can be removed from the {{Ic|URxvt.perl-ext}} list.}}<br />
<br />
'''Key commands:'''<br />
<br />
{| class="wikitable"<br />
! Key !! Description<br />
|-<br />
| Alt+u || Enter selection mode. The last URL on your screen will be selected. You can repeat {{ic|Alt+u}} to select the next upward URL.<br />
|-<br />
| k || Select next upward URL<br />
|-<br />
| j || Select next downward URL<br />
|-<br />
| Return || Open selected URL in browser and quit selection mode<br />
|-<br />
| o || Open selected URL in browser without quitting selection mode<br />
|-<br />
| y || Copy (yank) selected URL and quit selection mode<br />
|-<br />
| Esc || Cancel URL selection mode<br />
|}<br />
<br />
=== Simple tabs ===<br />
<br />
To add tabs to urxvt, add the following to your {{ic|~/.Xresources}}:<br />
URxvt.perl-ext-common: ...,tabbed,...<br />
<br />
To control tabs use:<br />
<br />
{| class="wikitable"<br />
! Key !! Description<br />
|-<br />
| Shift+Down || New tab<br />
|-<br />
| Shift+Left || Go to left tab<br />
|-<br />
| Shift+Right || Go to right tab<br />
|-<br />
| Ctrl+Left || Move tab to the left<br />
|-<br />
| Ctrl+Right || Move tab to the right<br />
|-<br />
| Ctrl+d || Close tab<br />
|}<br />
<br />
You can change the colors of tabs with the following:<br />
<br />
URxvt.tabbed.tabbar-fg: 2<br />
URxvt.tabbed.tabbar-bg: 0<br />
URxvt.tabbed.tab-fg: 3<br />
URxvt.tabbed.tab-bg: 0<br />
<br />
=== Advanced tab management ===<br />
<br />
Install the {{AUR|urxvt-tabbedex}} package from [[AUR]], then add the {{ic|tabbedex}} value to the {{ic|URxvt.perl-ext-common}} X resource in your {{ic|~/.Xresources}}:<br />
URxvt.perl-ext-common: ...,tabbedex,...<br />
<br />
{{Note|If you have previously used the {{ic|tabbed}} Perl extension and have defined the {{ic|tabbed}} value for the {{ic|URxvt.perl-ext-common}} X resource, please remove the {{ic|tabbed}} value first to avoid conflict with {{ic|tabbedex}}.}}<br />
<br />
By default, the "[NEW]" button (which is rarely used and usable only with the mouse) is disabled with tabbedex. You can reenable this feature by setting the {{ic|new-button}} to yes.<br />
URxvt.tabbed.new-button: true<br />
<br />
Tabs can be named with {{ic|Shift+ ↑}} ({{ic|Enter}} to confirm, {{ic|Escape}} to cancel).<br />
<br />
To automatically hide the tabs bar when only one tab is present, enable the following resource:<br />
URxvt.tabbed.autohide: true<br />
<br />
To prevent the last tab from closing Urxvt, enable the following resource:<br />
URxvt.tabbed.reopen-on-close: yes<br />
<br />
To start a new tab or cycle through tabs, use the following user commands: {{ic|<nowiki>tabbedex:(new|next|prev)_tab</nowiki>}}. Example of mappings:<br />
URxvt.keysym.Control-t: perl:tabbedex:new_tab<br />
URxvt.keysym.Control-Tab: perl:tabbedex:next_tab<br />
URxvt.keysym.Control-Shift-Tab: perl:tabbedex:prev_tab<br />
<br />
To define your own key bindings to rename a tab or move a tab to the right or to the left, use the following commands: {{ic|<nowiki>tabbedex:move_tab_(left|right)</nowiki>}} and {{ic|tabbedex:rename_tab}}. Example of mappings:<br />
URxvt.keysym.Control-Shift-Left: perl:tabbedex:move_tab_left<br />
URxvt.keysym.Control-Shift-Right: perl:tabbedex:move_tab_right<br />
URxvt.keysym.Control-Shift-R: perl:tabbedex:rename_tab<br />
<br />
{{Note|Redefining the keys used for the user commands will not disable the default mappings, you have to set the X resource {{ic|no-tabbedex-keys}} for that. However, currently it is not included in {{AUR|urxvt-tabbedex}} package. Consider using {{AUR|urxvt-tabbedex-git}} package instead:<br />
URxvt.tabbed.no-tabbedex-keys: true<br />
}}<br />
<br />
=== Fullscreen ===<br />
<br />
You can install the [[AUR]] package {{AUR|urxvt-fullscreen}}, and then set a key binding to put urxvt fullscreen.<br />
<br />
{{hc|~/.Xresources|<br />
...<br />
URxvt.perl-ext-common: ...,fullscreen,...<br />
URxvt.keysym.F11: perl:fullscreen:switch<br />
...<br />
}}<br />
<br />
=== Scrollwheel support ===<br />
<br />
Install {{AUR|urxvt-vtwheel}} from the [[AUR]] and add it to your Perl extensions within {{ic|~/.Xresources}}:<br />
<br />
URxvt.perl-ext-common: ...,vtwheel,...<br />
<br />
=== Changing font size on the fly ===<br />
<br />
Install {{AUR|urxvt-resize-font-git}} from the [[AUR]], add it to your Perl extensions within {{ic|~/.Xresources}}<br />
<br />
URxvt.perl-ext-common: ...,resize-font,...<br />
<br />
and add some key bindings, for example like this:<br />
<br />
URxvt.resize-font.smaller: C-Down<br />
URxvt.resize-font.bigger: C-Up<br />
<br />
For the Ctrl+Shift bindings to work, a default binding needs to be disabled (see discussion [http://wilmer.gaa.st/blog/archives/36-rxvt-unicode-and-ISO-14755-mode.html here]):<br />
<br />
URxvt.iso14755: false<br />
URxvt.iso14755_52: false<br />
<br />
=== Disabling Perl extensions ===<br />
<br />
If you do not use the Perl extension features, you can improve the security and speed by disabling Perl extensions completely.<br />
URxvt.perl-ext:<br />
URxvt.perl-ext-common:<br />
<br />
{{Note|If you use multiple Perl extension features, you can list them in succession, comma-separated: {{ic|URxvt.perl-ext-common:default,matcher,tabbed.}}}}<br />
<br />
== Colors ==<br />
<br />
By default, rxvt-unicode is compiled with color support. In addition to the default foreground and background colors, rxvt can display up to 256 colors (plus high-intensity bold/blinking/underlined and any mix of these).<br />
The look, feel, and function of rxvt-unicode is controlled by command-line arguments called X resources.<br />
<br />
A sample {{ic|~/.Xresources}} for an urxvt terminal with default colors but white fonts on a black background would be written as follow:<br />
<br />
{{hc|~/.Xresources|2=<br />
! Background color<br />
URxvt*background: black<br />
<br />
! Font color<br />
URxvt*foreground: white<br />
<br />
! Other colors<br />
URxvt*color0: black<br />
URxvt*color1: red3<br />
URxvt*color2: green3<br />
URxvt*color3: yellow3<br />
URxvt*color4: blue2<br />
URxvt*color5: magenta3<br />
URxvt*color6: cyan3<br />
URxvt*color7: gray90<br />
URxvt*color8: grey50<br />
URxvt*color9: red<br />
URxvt*color10: green<br />
URxvt*color11: yellow<br />
URxvt*color12: blue<br />
URxvt*color13: magenta<br />
URxvt*color14: cyan<br />
URxvt*color15: white<br />
}}<br />
<br />
It is also possible to specify the color values of foreground, background, cursorColor, cursorColor2, colorBD, colorUL as a number 0-15, as a convenient shorthand to reference the color name of color0-color15. See [[#Creating ~/.Xresources]] to create a commented {{ic|~/.Xresources}} file for {{ic|urxvt}}<br />
<br />
=== Xterm-like colors ===<br />
<br />
By default {{ic|urxvt}} uses the same colors as {{ic|xterm}} use except one. Add the following line at the end of your {{ic|~/.Xresources}} for xterm-like colors:<br />
{{hc|~/.Xresources|2=<br />
...<br />
URxvt*color12: rgb:5c/5c/ff<br />
}}<br />
then merge it contents with your current X resources configuration with:<br />
xrdb -merge ~/.Xresources<br />
and finally restart {{ic|urxvt}}.<br />
<br />
== Improving performance ==<br />
<br />
* Avoid the use of Xft fonts. If Xft fonts must be used, append {{Ic|<nowiki>:antialias=false</nowiki>}} to the setting value.[http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod#Can_I_speed_up_Xft_rendering_somehow]<br />
* Build rxvt-unicode with disabled support for unnecessary features, {{Ic|--disable-xft}} and {{Ic|--disable-unicode3}} in particular.<sup>[http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod#Rxvt_unicode_uses_gobs_of_memory_how]<br />
* Limit the number of {{Ic|saveLines}} (option {{Ic|-sl}}) in the scrollback buffer to reduce memory usage. [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod#Isn_t_rxvt_unicode_supposed_to_be_sm]<br />
** Use tmux for scrollback buffer and set saveLines to 0<br />
* [[#Disabling Perl extensions|Disable perl]]<br />
* Consider running {{Ic|urxvtd}} as a daemon accepting connections from {{Ic|urxvtc}} clients.<br />
<br />
=== Daemon-client ===<br />
<br />
==== Xinitrc ====<br />
<br />
See the ''Examples'' section in {{ic|man urxvtd}}. This is the preferred option.<br />
<br />
==== systemd ====<br />
<br />
{{Note|Regular users cannot execute systemctl power commands (reboot, poweroff, etc) when logged in to a urxvt client/daemon setup which is started through systemd, as the client is not part of the [[session]]. For this reason starting urxvt through systemd is discouraged.}}<br />
<br />
System service:<br />
<br />
{{hc|/etc/systemd/system/urxvtd@.service|<nowiki><br />
[Unit]<br />
Description=RXVT-Unicode Daemon<br />
<br />
[Service]<br />
User=%i<br />
ExecStart=/usr/bin/urxvtd -q -o<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Pass the username when [[Systemd#Using units|starting the service]]:<br />
<br />
urxvtd@''username''.service<br />
<br />
For a [[systemd/User]] service, place the following unit files in {{ic|~/.config/systemd/user}}:<br />
<br />
{{hc|urxvtd.service|<nowiki><br />
[Unit]<br />
Description=Urxvt Terminal Daemon<br />
Requires=urxvtd.socket<br />
<br />
[Service]<br />
ExecStart=/usr/bin/urxvtd -o -q<br />
Environment=RXVT_SOCKET=%t/urxvtd-%H<br />
<br />
[Install]<br />
WantedBy=</nowiki>''MyTarget''.target<br />
}}<br />
<br />
{{hc|urxvtd.socket|<nowiki><br />
[Unit]<br />
Description=urxvt daemon (socket activation)<br />
Documentation=man:urxvtd(1) man:urxvt(1)<br />
<br />
[Socket]<br />
ListenStream=%t/urxvtd-%H<br />
<br />
[Install]<br />
WantedBy=sockets.target<br />
</nowiki>}}<br />
<br />
== Cut and paste ==<br />
<br />
{{Note|With the use of a terminal multiplexer, urxvt (or any terminal emulator) {{Ic|CLIPBOARD}} integration will not be effective, since it will not be possible to select all of the desired text in a straightforward fashion or at all, in some cases (e.g., when the active multiplexed terminal is changed to another one and then back to the original one, and one selects text beyond what is visible, which causes text from the other terminal to be displayed). Obviously this is due to the fact that the terminal emulator lacks the ability to distinguish between multiplexed terminals. Therefore, it would be effectively redundant for one who always uses a terminal multiplexer capable of maintaining a scrollback buffer and integrating with {{ic|CLIPBOARD}} (e.g. [[tmux]] with [[tmux#Key bindings|customized key bindings]]) to integrate {{ic|CLIPBOARD}} with urxvt.}}<br />
<br />
For users unfamiliar with [[Xorg]] data transfer methods, the exchange of information to and from rxvt-unicode can become a burden. Suffice to say that rxvt-unicode uses cut buffers which are typically loaded into the current {{Ic|PRIMARY}} selection by default. [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod#THE_SELECTION_SELECTING_AND_PASTING_] Users are urged to review [[Wikipedia:X Window selection]] for additional information.<br />
<br />
=== Default key bindings ===<br />
<br />
Default X key bindings will still work for copying and pasting. After selecting the text Ctrl+Insert or Ctrl+Alt+C can be used to copy and Shift+Insert or Ctrl+Alt+V to paste.<br />
<br />
=== Custom key bindings ===<br />
<br />
To enable copy/paste using Ctrl+Shift+c/Ctrl+Shift+v, or similar, you will need to edit your .Xresources. First add the extension:<br />
{{bc|<br />
URxvt.perl-ext-common: default,clipboard<br />
}}<br />
<br />
Then disable iso14755:<br />
{{bc|<br />
URxvt.iso14755: False<br />
}}<br />
<br />
And bind the keys:<br />
{{bc|<br />
URxvt.keysym.Shift-Control-C: perl:clipboard:copy<br />
URxvt.keysym.Shift-Control-V: perl:clipboard:paste<br />
}}<br />
<br />
If using xsel (which is the default), use:<br />
{{bc|<br />
URxvt.clipboard.copycmd: xsel -ib<br />
URxvt.clipboard.pastecmd: xsel -ob<br />
}}<br />
<br />
These two settings can be changed for other clipboard managers such as xclip.<br />
<br />
=== Clipboard management ===<br />
<br />
See [[Clipboard#List of clipboard managers]]<br />
<br />
=== Automatic script management ===<br />
<br />
{{Note|Since version 9.20, {{Pkg|rxvt-unicode}} comes with a new {{ic|selection-to-clipboard}} extension that supersedes the scripts below. Enable it like any other extension.}}<br />
Skottish[https://bbs.archlinux.org/viewtopic.php?pid=506845#p506845] created a Perl script to automatically copy any selection in rxvt-unicode to the X clipboard. Save the following as {{ic|/usr/lib/urxvt/perl/clipboard}}:<br />
<br />
{{bc|<nowiki><br />
#! /usr/bin/perl<br />
<br />
sub on_sel_grab {<br />
my $query=quotemeta $_[0]->selection;<br />
$query=~ s/\n/\\n/g;<br />
$query=~ s/\r/\\r/g;<br />
system( "echo -en " . $query . " | xsel -i -b -p" );<br />
}<br />
</nowiki>}}<br />
<br />
Xyne has also created his own variation of Skottish's script named {{AUR|urxvt-clipboard}} which is available in the [[AUR]] that allows the user to paste the selection with {{ic|Ctrl+V}} instead of only with a middle mouse click:<br />
<br />
{{bc|<nowiki><br />
#! /usr/bin/perl<br />
<br />
sub on_sel_grab<br />
{<br />
my $query = $_[0]->selection;<br />
open (my $pipe,'|-','xsel -ib') or die;<br />
print $pipe $query;<br />
close $pipe;<br />
open (my $pipe,'|-','xsel -ip') or die;<br />
print $pipe $query;<br />
close $pipe;<br />
}<br />
</nowiki>}}<br />
<br />
It also requires {{Pkg|xsel}} and needs to be enabled in the {{Ic|*perl-ext-common}} or {{Ic|*perl-ext}} field in {{ic|~/.Xresources}}. For example:<br />
URxvt.perl-ext-common: default,clipboard<br />
<br />
The [[AUR]] package {{AUR|urxvt-perls-git}} is another option one can use. {{AUR|urxvt-perls-git}} includes the same functionality as {{AUR|urxvt-clipboard}}, in addition to the keyboard-select and url-select Perl extensions.<br />
<br />
== Improved Kuake-like behavior in Openbox ==<br />
<br />
This was originally posted on the forum by Xyne [https://bbs.archlinux.org/viewtopic.php?pid=550380], and it relies on the {{Pkg|xdotool}} found in the [[official repositories]].<br />
<br />
=== Scriptlets ===<br />
<br />
Save this scriptlet from the {{Ic|urxvtc}} man page somewhere on your system as {{ic|urxvtc}} (e.g., in {{ic|~/.config/openbox}}):<br />
<br />
{{bc|<br />
#!/bin/sh<br />
<br />
urxvtc "$@"<br />
if [ $? -eq 2 ]; then<br />
urxvtd -q -o -f<br />
urxvtc "$@"<br />
fi<br />
}}<br />
<br />
and save this one as {{ic|urxvtq}}:<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
wid=$(xdotool search --classname urxvtq)<br />
if [ -z "$wid" ]; then<br />
/path/to/urxvtc -name urxvtq -geometry 80x28<br />
wid=$(xdotool search --classname urxvtq | head -1)<br />
xdotool windowfocus "$wid"<br />
xdotool key Control_L+l<br />
else<br />
if [ -z "$(xdotool search --onlyvisible --classname urxvtq 2>/dev/null)" ]; then<br />
xdotool windowmap "$wid"<br />
xdotool windowfocus "$wid"<br />
else<br />
xdotool windowunmap "$wid"<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
A previous version of {{Pkg|xdotool}} introduced a bug which disabled recognition of visible windows and thus led some users to use the following scriptlet in place of the previous one. This is no longer necessary as of {{Pkg|xdotool}} >= 1.20100416.2809, but it has been left here for future reference.'<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
wid=$(xprop -name urxvtq | grep 'WM_COMMAND' | awk -F ',' '{print $3}' | awk -F '"' '{print $2}')<br />
if [ -z "$wid" ]; then<br />
/path/to/urxvtc -name urxvtq -geometry 200x28<br />
wid=$(xprop -name urxvtq | grep 'WM_COMMAND' | awk -F ',' '{print $3}' | awk -F '"' '{print $2}')<br />
xdotool windowfocus "$wid"<br />
xdotool key Control_L+l<br />
else<br />
if [ -z "$(xprop -id "$wid" | grep 'window state: Normal' 2>/dev/null)" ]; then<br />
xdotool windowmap "$wid"<br />
xdotool windowfocus "$wid"<br />
else<br />
xdotool windowunmap "$wid"<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
Make sure that you change {{Ic|/path/to/urxvtc}} to the actual path to the {{ic|urxvtc}} scriptlet that you saved above. We will be using {{ic|urxvtc}} to launch both regular instances of {{Ic|urxvt}} and the kuake-like instance.<br />
<br />
=== urxvtq with tabbing ===<br />
<br />
If you want to have tabs in your kuake-like {{ic|urxvtc}} (here called {{ic|urxvtq}}) just replace the third line in your {{ic|urxvtq}}:<br />
wid=$(xdotool search --name urxvtq)<br />
with:<br />
wid=$(xdotool search --name urxvtq | grep -m 1 "" )<br />
<br />
To activate tab support, you can either replace the fifth line of your {{ic|urxvtq}}:<br />
/path/to/urxvtc -name urxvtq -geometry 80x28<br />
with:<br />
/path/to/urxvtc -name urxvtq -pe tabbed -geometry 80x28<br />
or replace this line of your {{ic|~/.Xresources}} file:<br />
URxvt.perl-ext-common: default,matcher<br />
with<br />
URxvt.perl-ext-common: default,matcher,tabbed<br />
<br />
==== Tab control ====<br />
<br />
{| class="wikitable"<br />
! Key !! Description<br />
|-<br />
| Shift+Left || Switch to the tab left of the current one<br />
|-<br />
| Shift+Right || Switch to the tab right of the current one<br />
|-<br />
| Shift+Down || Create a new tab<br />
|}<br />
<br />
You can also use your mouse to switch the tabs by clicking the wished one and create a new tab by clicking on ''[NEW].\\''<br />
<br />
To close a tab just enter {{Ic|exit}} like you would to normally close a terminal.<br />
<br />
=== Openbox configuration ===<br />
<br />
Now add the following lines to the {{Ic|<applications>}} section of {{ic|~/.config/openbox/rc.xml}}:<br />
<br />
{{bc|1=<br />
<application name="urxvtq"><br />
<decor>no</decor><br />
<position force="yes"><br />
<x>center</x><br />
<y>0</y><br />
</position><br />
<desktop>all</desktop><br />
<layer>above</layer><br />
<skip_pager>yes</skip_pager><br />
<skip_taskbar>yes</skip_taskbar><br />
<maximized>Horizontal</maximized><br />
</application><br />
}}<br />
<br />
and add these lines to the {{Ic|<keyboard>}} section:<br />
<br />
{{bc|1=<br />
<keybind key="W-t"><br />
<action name="Execute"><br />
<command>/path/to/urxvtc</command><br />
</action><br />
</keybind><br />
<keybind key="W-grave"><br />
<action name="Execute"><br />
<execute>/path/to/urxvtq</execute><br />
</action><br />
</keybind><br />
}}<br />
<br />
Here too you need to change the {{Ic|/path/to/*}} lines to point to the scripts that you saved above. Save the file and then reconfigure Openbox. You should now be able to launch regular instances of urxvt with {{ic|Super+T}}, and toggle the kuake-like console with {{ic|Super+'''`'''}} (the grave key also known as the backtick).<br />
<br />
=== Further configuration ===<br />
<br />
The advantage of this configuration over the urxvt kuake Perl script is that Openbox provides more keybinding options such as modifier keys. The kuake script hijacks an entire physical key regardless of any modifier combination. Review the [http://openbox.org/wiki/Help:Bindings Openbox bindings documentation] for the full range or possibilities.<br />
<br />
The [http://openbox.org/wiki/Help:Applications Openbox per-app settings] can be used to further configure the behavior of the kuake-like console (e.g. screen position, layer, etc.). You may need to change the "geometry" parameter in the {{ic|urxvtq}} scriptlet to adjust the height of the console.<br />
<br />
=== Related scripts ===<br />
<br />
* hbekel has posted a generalized version of the {{ic|urxvtq}} [https://bbs.archlinux.org/viewtopic.php?pid=550380#p550380 here] which can be used to toggle any application using {{Pkg|xdotool}}.<br />
* http://www.jukie.net/~bart/blog/20070503013555 - A script for opening URLs with your keyboard instead of mouse with urxvt.<br />
<br />
== Troubleshooting ==<br />
<br />
=== ~/.Xresources is not being sourced ===<br />
<br />
In some cases where ''urxvt'' does not acknowledge {{ic|~/.Xresources}}, you may need to add {{ic|xrdb -merge ~/.Xresources}} to your {{ic|~/.xinitrc}} file. See [[X resources]] for more information.<br />
<br />
=== Transparency not working after upgrade to v9.09 ===<br />
<br />
The rxvt-unicode developers removed compatibility code for a lot of non standard wallpaper setters with this update. Using a non compatible wallpaper setter will break transparency support. Recommended wallpaper setters:<br />
<br />
* [[feh]]<br />
* hsetroot<br />
* esetroot<br />
<br />
To make true transparency work, make sure to comment URxvt.tintColor and URxvt.inheritPixmap.<br />
<br />
=== Remote hosts ===<br />
<br />
If you are logging into a remote host, you may encounter problems when running text-mode programs under rxvt-unicode. This can be fixed by installing {{Pkg|rxvt-unicode-terminfo}} on the remote host or by copying {{ic|/usr/share/terminfo/r/rxvt-unicode}} from your local machine to your host at {{ic|~/.terminfo/r/rxvt-unicode}}; same for rxvt-unicode-256color.<br />
<br />
Some remote systems do not change title automatically unless you specify TERM=xterm. To fix the issue add this line to .bashrc on the remote machine:<br />
<br />
PROMPT_COMMAND='echo -ne "\033]0;${USER}@${HOSTNAME}:${PWD}\007"'<br />
<br />
=== Using rxvt-unicode as gmrun terminal ===<br />
<br />
Unlike some other terminals, urxvt expects the arguments to {{Ic|-e}} to be given separately, rather than grouped together with quotes. This causes trouble with gmrun, which assumes the opposite behavior. This can be worked around by putting an "eval" in front of gmrun's "Terminal" variable in {{ic|.gmrunrc}}:<br />
<br />
Terminal = eval urxvt<br />
TermExec = ${Terminal} -e<br />
<br />
(gmrun uses {{ic|/bin/sh}} to execute commands, so the "eval" is understood here.) The "eval" has the side-effect of "breaking up" the argument to {{Ic|-e}} in the same way that {{Ic|$@}} does in [[Bash]], making the command intelligible to urxvt.<br />
<br />
=== My numerical keypad acts weird and generates differing output? (e.g. in vim) ===<br />
<br />
Some Debian GNU/Linux users seem to have this problem, although no specific details were reported so far. It is possible that this is caused by the wrong TERM setting, although the details of whether and how this can happen are unknown, as TERM=rxvt should offer a compatible keymap. See the answer to the previous question, and please report if that helped.<br />
<br />
However, using the ''xmodmap'' program ({{Pkg|xorg-xmodmap}}), you can re-map your number pad keys back.<br />
<br />
1. Check the keycode that your numerical keypad (numpad) generates using {{ic|xev}} program.<br />
<br />
* Start the {{ic|xev}} program<br />
* Press your number pad keys and look for ''... keycode xxx ...'' in {{ic|xev}}'s output. For example, numpad 1 in my keyboard is also "End" key, that have a ''''keycode 87''''.<br />
<br />
2. Create or modify your xmodmap file, usually {{ic|~/.Xmodmap}}, with the content representing your keycode.<br />
<br />
Example of xmodmap file with number pad keycode:<br />
<br />
{{bc|1=<br />
keycode 63 = KP_Multiply<br />
keycode 79 = Home KP_7<br />
keycode 80 = Up KP_8<br />
keycode 81 = Prior KP_9<br />
keycode 82 = KP_Subtract<br />
keycode 83 = Left KP_4<br />
keycode 84 = KP_5<br />
keycode 85 = Right KP_6<br />
keycode 86 = KP_Add<br />
keycode 87 = End KP_1<br />
keycode 88 = Down KP_2<br />
keycode 89 = Next KP_3<br />
keycode 90 = Insert KP_0<br />
keycode 91 = Delete KP_Decimal<br />
keycode 112 = Prior<br />
keycode 117 = Next<br />
}}<br />
<br />
3. Load your xmodmap file at X session start-up.<br />
<br />
For example, in {{ic|~/.xinitrc}} file add:<br />
<br />
...<br />
xmodmap ~/.Xmodmap<br />
...<br />
<br />
=== Pseudo-tty ===<br />
<br />
The following error is likely caused by {{ic|/dev/pts}} having been mounted with the wrong options.<br />
<br />
urxvt: cannot initialize pseudo-tty, aborting.<br />
<br />
Remove {{ic|/dev/pts}} from {{ic|/etc/fstab}} and fix the current mount options with:<br />
<br />
sudo mount -o remount,gid=5,mode=620 /dev/pts<br />
<br />
See also [https://mailman.archlinux.org/pipermail/arch-dev-public/2013-August/025332.html], {{bug|36548}}, and [https://bbs.archlinux.org/viewtopic.php?pid=1318127].<br />
<br />
=== Key combinations do not work ===<br />
<br />
See [http://vim.wikia.com/wiki/Get_Alt_key_to_work_in_terminal?useskin=monobook Get Alt key to work in terminal].<br />
<br />
=== Slow performance when drawing glyphs ===<br />
<br />
Some programs like alsamixer and xprop do not perform well with some graphics drivers and in consequence redraw very slowly. The option "skipBuiltinGlyphs" for {{ic|~/.Xresources}} or the command line option {{ic|-sbg}} may fix this. One possible solution is to add the following to {{ic|~/.Xresources}}:<br />
<br />
URxvt*skipBuiltinGlyphs: true<br />
<br />
== External resources ==<br />
<br />
* [http://software.schmorp.de/pkg/rxvt-unicode.html rxvt-unicode] - Official site<br />
* [http://cvs.schmorp.de/rxvt-unicode/ Source Code] - Browseable CVS<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod rxvt-unicode FAQ] - Official FAQ<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod rxvt-unicode Reference] - Official manual page<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/src/urxvt.pm urxvtperl] - Official Perl extension reference</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Termite&diff=409527Termite2015-11-18T17:59:11Z<p>Airblader: Fix i3 remark and provide solution</p>
<hr />
<div>[[Category:Terminal emulators]]<br />
[[ja:Termite]]<br />
[https://www.github.com/thestinger/termite Termite] is a minimal [[:Category:Terminal emulators|terminal emulator]] designed for use with tiling [[window manager]]s. It is a ''modal'' application, similar to [[Vim]], with an insert mode and command mode where keybindings have different functions. Termite is based on the [https://developer.gnome.org/vte/unstable/ VTE] library.<br />
<br />
The configuration file allows to change colors and set some options. Termite supports transparency along with both the 256 color and true color (16 million colors) palettes. It has a similar look and feel to [[urxvt]].<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|termite}} package, or {{AUR|termite-git}} for the development version.<br />
<br />
== Usage ==<br />
<br />
Termite starts in insert mode by default. Text may be selected using the mouse, or by using command-mode keys. In insert mode, {{ic|Ctrl-Shift-c}} is used to copy selected text to the [[X]] clipboard, {{ic|Ctrl-Shift-v}} to paste. {{ic|Ctrl-tab}} starts scrollback completion, and {{ic|Ctrl-Shift-up}} / {{ic|Ctrl-Shift-down}} scroll the screen up or down.<br />
<br />
{{ic|Ctrl-Shift-space}} enters command-mode. Many commands are borrowed from [[Vim]], for example {{ic|v}} for visual mode, {{ic|Shift-v}} for visual line mode, {{ic|Ctrl-v}} for visual block mode, {{ic|y}} to copy ("yank") selected text, {{ic|/}} and {{ic|?}} for searching, {{ic|w}}, {{ic|b}}, {{ic|^}}, {{ic|$}} for movement, and {{ic|Escape}} to go back to insert mode.<br />
<br />
== Configuration ==<br />
Termite looks for configuration files in {{ic|$XDG_CONFIG_HOME/termite/config}}, {{ic|~/.config/termite/config}}, {{ic|$XDG_CONFIG_DIRS/termite/config}} and {{ic|/etc/xdg/termite.cfg}}. The configuration file is used to change options such as font, colors, window hints, etc. The configuration file is in ''ini'' format, with three sections: ''options'', ''colors'', and ''hints''.<br />
<br />
=== Font ===<br />
Fonts are specified in the format {{ic|1=font=<font_name> <font_size>}} under the ''options'' section. {{ic|<font_name>}} is specified according to [[fontconfig]], not [[X Logical Font Description|Xft]]. Use {{ic|fc-list}} to see which fonts are available on the system (see also [[Font configuration#Font paths]]).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[options]<br />
font = Monospace 9<br />
font = Terminus (TTF) 8<br />
font = Droid Sans Mono 8}}<br />
<br />
=== Colors ===<br />
Colors consist of either a 24-bit hex value (e.g. {{ic|#4a32b1}}), or an rgba vector (e.g. {{ic|rgba(16, 32, 64, 0.5)}}). Valid properties for colors are {{ic|foreground}}, {{ic|foreground_bold}}, {{ic|foreground_dim}}, {{ic|background}}, {{ic|cursor}}, and {{ic|colorN}} (where N is an integer from zero through 254; used to assign a 24-bit color value to terminal colorN).<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
foreground = #dcdccc<br />
background = #3f3f3f}}<br />
<br />
== Transparency ==<br />
As of version 9, Termite supports true transparency via color definitions that specify an alpha channel value [https://github.com/thestinger/termite/issues/191]. This requires a compositor to be running, such as [[Compton]] or {{pkg|xcompmgr}}. Most compositors do not require special configuration for Termite to use transparency.<br />
<br />
{{hc|~/.config/termite/config|2=<br />
[colors]<br />
background = rgba(63, 63, 63, 0.8)<br />
}}<br />
<br />
{{Note|In [[i3]], in stacked/tabbed layout, this shows all windows "stacked" on top of each other, in the order they were most recently in the foreground, rather than showing the desktop (the root window) directly behind Termite. This is due to i3 reordering windows rather than hiding invisible windows in tiling mode. You can configure your compositor to make windows with {{ic|1=_NET_WM_STATE=_NET_WM_STATE_HIDDEN}} fully transparent to solve this. For example, for compton use<br />
{{hc|head=~/.compton.conf|output=opacity-rule = [<br />
"0:_NET_WM_STATE@:32a *= '_NET_WM_STATE_HIDDEN'"<br />
];}}<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Colored ls output ===<br />
<br />
{{Deletion|1=This bug should have been [http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=a960c31 fixed] on 2015-10-02, and be available with the next {{Pkg|coreutils}} release.|section=Colored ls output}}<br />
<br />
For colored {{ic|ls}} output it is necessary to use a custom LS_COLORS [[environment variable]], which can be set with a {{ic|dircolors}} file. Generate one with:<br />
<br />
$ dircolors -p > ~/.dircolors<br />
<br />
Then edit {{ic|~/.dircolors}} file, and append<br />
<br />
TERM xterm-termite<br />
<br />
to the end of the list of terminals, and save the file.<br />
<br />
For [[Bash]] in {{ic|~/.bashrc}} and [[Zsh]] in {{ic|~/.zshrc}}, add:<br />
<br />
eval $(dircolors ~/.dircolors)<br />
<br />
and restart the terminal. For [[fish]], add <br />
<br />
eval (dircolors -c ~/.dircolors | sed 's/>&\/dev\/null$//')<br />
<br />
to {{ic|~/.config/fish/config.fish}} and relogin or reload the config via:<br />
<br />
. ~/.config/fish/config.fish<br />
<br />
=== Ctrl-T not working ===<br />
<br />
Ctrl-T should open a new tab, but it sometimes fails with certain shells. If the termite window outputs {{ic|no directory uri set}} when this happens, the solution is to add <br />
<br />
. /etc/profile.d/vte.sh<br />
<br />
to your {{ic|~/.zshrc}}.<br />
<br />
See [http://unix.stackexchange.com/questions/93476/gnome-terminal-keep-track-of-directory-in-new-tab this stackexchange question] for more details.<br />
<br />
== See also ==<br />
<br />
* [https://github.com/thestinger/termite/blob/master/README.rst Termite readme]</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Talk:VCS_package_guidelines&diff=399471Talk:VCS package guidelines2015-09-11T22:58:13Z<p>Airblader: /* Guidelines on updating version numbers */</p>
<hr />
<div>== Numeric vs Date Standard in Git pkgver ==<br />
<br />
I'd like to see a standard emerge in AUR Git packages, but standards have to work down to the lowest common denominator. Only a small minority of GitHub projects properly tag their releases, so there can be only two LCD standards for Git packages: the Numeric standard, e.g. ("r1581.2b039da") and the Date standard, e.g. ("2014-01-01"). The date standard is much more readable, and actionable, and has the additional benefit of being backwards compatible with older Git packages.<br />
<br />
I don't know if any standard can emerge even if we wanted it to, but please allow me to at least add the Date standard to the VCS package guidelines wiki (as opposed to scrubbing it, :).<br />
<br />
:Using the commit date would be incorrect because it doesn't refer to a specific commit and the dates are not always sequential. It would be even more wrong if it was the build date, as that doesn't refer to anything to do with the version. -- [[User:thestinger|thestinger]] 21:33, 23 January 2015 (UTC)<br />
<br />
::''it doesn't refer to a specific commit''<br />
::<br />
::Neither does "r1581.2b039da" refer to a specific commit without the .git repo cmdline interaction, and it is considered best practice to prune $pkgdir of .git:<br />
::<br />
find "$pkgdir" -type d -name .git -exec rm -r '{}' +<br />
::<br />
::Can you explain what you mean by "the dates are not always sequential"? The Date standard looks like this:<br />
::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::<br />
::It displays the latest commit date from the upstream Git repo.<br />
::<br />
::In the edge case of breaking changes occurring upstream in Git repos on the same day, then package maintainers should increment pkgrel. In practice, "2014-01-01" is much more readable and useful than "r1581.2b039da". The readability benefits of "2014-01-01" vs. "r1581.2b039da" should not be underestimated due to edge cases. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 18:39, 24 January 2015 (UTC)<br />
:::A git commit id certainly refers to a specific commit. I don't know why you think this has anything to do with shipping the VCS repository in the package. The commit date of the most recent commit may be from 20 weeks ago while the earlier commits were from last week. Git does not have a linear history. It's not going to be changed to use a version format where it can go both backwards and forwards with no way of tracing it back to the commit. Readability is worthless if the information isn't meaningful... There are 2 hard requirements: newer revisions must have higher package versions without exceptions, and it must be possible to trace it back to a commit to properly identify and report bugs. -- [[User:thestinger|thestinger]] 18:53, 24 January 2015<br />
:::<br />
::::<br />
::::I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.<br />
::::<br />
::::Can you show me where to find "r1581.2b039da" on a GitHub/BitBucket repo? It doesn't exist anywhere that I can see. You need to have the repo locally, then cd into the Git repo and run:<br />
::::<br />
git rev-list --count HEAD<br />
::::<br />
::::That is work-intensive, and it conflicts with the best practice of pruning AUR packages of .git repos.<br />
::::<br />
::::I previously used the Wiki-recommended Numeric standard, so it's not like I haven't used it. I switched to the Date standard, updating hundreds of packages to reflect it. Why do you suppose that is?<br />
::::<br />
:::: ''Readability is worthless if the information isn't meaningful''<br />
::::You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581". I say this after maintaining for years, hundreds of Git packages in the AUR. You can tell by grepping `pacman -Q` exactly which AUR git packages are out of date with a two-second visit to GitHub. The Date standard is incredibly actionable and pragmatic not to mention simple and immediately understandable by anyone.<br />
::::<br />
:::: ''newer revisions must have higher package versions without exceptions''<br />
::::<br />
::::Not a problem: "2014-01-01" < "2014-01-02"<br />
::::<br />
:::: ''it must be possible to trace it back to a commit to properly identify and report bugs''<br />
::::<br />
:::: Given how frequently "stable" Go packages and C packages pull in Git dependencies as part of their build process without specifying a certain commit, I disagree with this proposition. Why would recording the version of acmedaemon as 1.5, when it pulls in Git packages without specifying commit ID, be all that different in bug reports than "2014-01-01"? In both cases, you will not be able to track down the exact cause of the bug by commit. In both cases, you will in all likelihood end up consulting the build date. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 03:32, 25 January 2015 (UTC)<br />
<br />
:::::''I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.''<br />
:::::In your scenerio, 2b039da is the short version of the commit hash and does point to a specific commit. As for where you find it on Github, it's listed on the commit log, of course. Just look at the right hand side of the page.<br />
:::::''You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581".''<br />
:::::In this case, human readability really is meaningless. Machine readability is all that matters.<br />
:::::''Not a problem: "2014-01-01" < "2014-01-02"''<br />
:::::And what happens when the commit after that is dated 2013-12-31? As thestinger pointed out, Git is not linear.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 03:40, 25 January 2015 (UTC)<br />
<br />
::::::''2b039da is the short version of the commit hash''<br />
::::::<br />
::::::Can this information be easily compared on GitHub to your local package version to check if it is out of date? The answer is no.<br />
::::::<br />
::::::It is not actionable, except by cloning the repo yourself, running the Git command, and then manually scanning the Git log for short versions. It's very work-intensive.<br />
::::::<br />
::::::''Git is not linear''<br />
::::::<br />
::::::Neither are stable packages on PyPi: https://pypi.python.org/pypi/tackpy/0.9.9a<br />
::::::<br />
::::::Pacman views the upgrade of 0.9.9 -> 0.9.9a as a downgrade. See https://aur.archlinux.org/packages/python2-tackpy for a real world example of this edge case. Edge cases should be no reason to prevent readers of the wiki to make informed choices about Git packaging standards. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:08, 25 January 2015 (UTC)<br />
<br />
:::::::Yes, the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page.<br />
:::::::As for PyPi's versioning scheme, their choice is different than what Arch's vercmp assumes. The packager needs to take this into account, just as all packagers must take upstream's idiosyncrasies into account. I don't see how it's relevant here.<br />
:::::::You also never answered my question, what happens when the last commit is dated before the commit previous to it? This question is critical, as it would cause your versioning scheme to go backwards by any and all measures. That makes it unacceptable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:15, 25 January 2015 (UTC)<br />
<br />
::::::::Incorrect.<br />
::::::::<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)<br />
::::::::<br />
::::::::The output of the above command does not correspond to any piece of information on GitHub.<br />
::::::::<br />
::::::::If PyPi packagers should take edge cases into account for PyPi packages, then they should do the same for Git packages. Edge cases aren't reason enough to scrub a competing standard from the wiki. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:23, 25 January 2015 (UTC)<br />
<br />
:::::::::I'm sorry if you can't find this information on GitHub. It's very, very plainly displayed in the places I already pointed you to. If you would take a minute to check instead of just jumping at me, you might find it.<br />
:::::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:31, 25 January 2015 (UTC)<br />
<br />
::::::::::''the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page''.<br />
::::::::::<br />
::::::::::This is (partially) incorrect. The short hash of each commit is not listed. What is listed in the commit log is the truncated commit ID.<br />
::::::::::<br />
::::::::::The revision count point I will retract. It didn't appear to work for my own Git repos, but that was because I ran the command from a Git subrepo (edge case :). The date still has the advantage of being more human readable than r1582. If a package has version 2011-10-22, I will know this project is either unmaintained, or it's been a really long time since I last rebuilt it. All without leaving the terminal. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:33, 25 January 2015 (UTC)<br />
<br />
::::::::::It's also very easy to look up or link to commits via the abbreviated commit hashes or proper identifiers produced by {{ic|git describe}}. -- [[User:thestinger|thestinger]] 04:33, 25 January 2015 (UTC)<br />
<br />
::::::That has nothing to do with non-linear history. It has to do with an incompatibility between Pacman's version comparison and the one chosen by the project. There are ways of dealing with that, but it has nothing to do with this discussion. -- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
:::::The ideal version is the one produced by {{ic|git describe}}, because it's easily understood by humans (last tag, commits since last tag, abbreviated commit), is also understood by the various Git commands and GitHub and is monotonically increasing thanks to the inclusion of the last version and revision count since then. The versions it produces ({{ic|10-7-g8537989}}) can be directly used with commands like {{ic|git show}}. Unlike the build date, it identifies a unique revision of the project, including the state of any submodules.<br />
<br />
:::::The only case where another method should be used is when the project doesn't yet have any tagged release or does the releases in a way that's not very sane. The releases ''should'' be tagged on master with additional tags in stable branches for fixes backported to old releases. If this isn't the case, the {{ic|git describe}} output needs to be emulated. A date is a poor way of doing that, because it's not connected to a specific point in the revision history.<br />
<br />
:::::The only case where the commit date would work is if Git is being used as a crippled centralized version control system. If all commits get created against master (no merging branches or patches) in a centralized repository where the system clock is never moved backwards, it could work... but that's not the reality of non-linear, distributed version control.<br />
<br />
:::::A build date is even worse, because it only refers to the local state of time and the local state of the repository. Commits from before that timestamp will often be pushed to the repository.<br />
<br />
:::::-- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
::::::A packaging standard must be compatible with the lowest common denominator. A minority of Git repos are properly tagged. The Date works as a standard, tags do not.<br />
::::::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::::::<br />
::::::The output of the above command shows the date of the most recent commit. If the most recent commit date happens to come before the date of a previous commit, I do understand this is suboptimal, but I consider it an edge case. Even in big projects with contributors in different time zones you will typically see branches merged in with PRs. PRs reset the date to something recent. The linearity of Git is rarely problematic, but I do see where you're coming from (I'm also a happy user of archversion for keeping packages up to date, though archversion works with the Date standard too :) --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:59, 25 January 2015 (UTC)<br />
<br />
:::::::The {{ic|git describe}} versioning system is the standard defined and used by Git itself. The dashes need to be converted into dots for {{ic|pkgver}} and an {{ic|r}} ''may'' be inserted to make it clearer which part is the revision number. If version-based tags on master are available, this is the only sane way to do it.<br />
<br />
:::::::Git defaults to fast-forwarding / applying patches without merge commits, as long as there are no conflicts. GitHub will ''always'' generate a merge commit but that's not true for anything applied / merged by the developers and then pushed to master. -- [[User:thestinger|thestinger]] 05:24, 25 January 2015 (UTC)<br />
<br />
:::::::You've made the claim that most git repos aren't properly tagged, not only now but to me previously. Do you have anything to back that up? IME, the large majority of projects that are in a usable state are either tagged or get tagged as they become stable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 05:27, 25 January 2015 (UTC)<br />
<br />
::::::::OK:<br />
::::::::<br />
git init<br />
::::::::<br />
::::::::You now have your very own untagged Git repo :).<br />
::::::::<br />
::::::::The majority of Git repos are untagged. If you want to have a standard compatible with the lowest common denominator, by definition you cannot depend on tags being there.<br />
::::::::<br />
::::::::I regularly package Git software in the alpha stages and software maintained by people who are unfamiliar with tagging or aren't bothered to tag. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:15, 25 January 2015 (UTC)<br />
<br />
::::As suggested in [[VCS package guidelines#Fallback]], I think the only date that can be used is the build date: for example I've recently used it in [https://aur.archlinux.org/packages/te/textadept-common-git/PKGBUILD a PKGBUILD] for a repo without tags or branches, also appending the first 7 characters of the commit hash (the repo is not cloned, so I could only use ''git-ls-remote''). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:30, 25 January 2015 (UTC)<br />
<br />
== Updating a CVS repo ==<br />
<br />
I don't use cvs. How can you describe the pkgver for cvs (for pacman 4.1)? <br><br />
-- [[User:Dracorp|Dracorp]] ([[User talk:Dracorp|talk]]) 09:31, 6 April 2013 (UTC)<br />
<br />
:CVS is not supported in pacman 4.1 like the other VCS tools. You will need to update pkgver manually until CVS support is added.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 22:44, 15 April 2013 (UTC)<br />
<br />
::Yeah, but how about mentioning that in the article (as well as giving a download example)? Even if it's not that common anymore.<br />
::--[[User:Det|Det]] ([[User talk:Det|talk]]) 22:39, 2 May 2013 (UTC)<br />
<br />
:::The download example can still be found in {{ic|/usr/share/pacman/}}. The next version of the ABS package should update it a bit so the download happens in the prepare function where it belongs. As for pkgver, I think the generic example using date covers that, as there's not a way to get a version number from a CVS repo. Maybe a note to that effect?<br />
::: -- [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 07:17, 15 May 2013 (UTC)<br />
<br />
::::That makes the most sense, but it might also be a good idea to rename the [[VCS PKGBUILD Guidelines#Fallback|"Fallback"]] section to something like "Fallback / CVS" to make it more obvious even when you're just checking out the table of contents.<br />
<br />
::::But as for ABS, as far as I can tell the last commit was over [https://projects.archlinux.org/abs.git/log/ 8 months] ago.<br />
::::--[[User:Det|Det]] ([[User talk:Det|talk]]) 05:54, 19 May 2013 (UTC)<br />
<br />
:::::Hmm, there were a number of patches submitted last month for cleaning up the prototypes, looks like none have been committed yet. I do remember a discussion (IRC maybe?) questioning the proper place for the prototypes, so maybe that's why? Looking at the patches, I was mistaken anyway; they didn't update the darcs or cvs prototypes. Simple enough, I'll send in a patch myself.<br />
:::::--[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 08:22, 19 May 2013 (UTC)<br />
<br />
: I use this dirty hack: {{ic|<nowiki>cvs history -c -a | cut -d' ' -f2 | sort -u | tail -n 1 | sed 's|-||g"</nowiki>}} ; could probably be improved.<br />
:--[[User:Buhman|Buhman]] ([[User talk:Buhman|talk]]) 18:00, 6 June 2013 (UTC)<br />
<br />
<br />
== pkgver function for hg based on tags ==<br />
<br />
I recent came across a way with hg to show the most recent tag, as well as the number of commits from this tag (similar to the output of {{ic|git describe}}.) <br />
<br />
{{hc|<nowiki>pkgver() {<br />
cd local_repo<br />
hg log -r . --template '{latesttag}.{latesttagdistance}.{node|short}\n'<br />
}</nowiki>|<br />
3.0.1.40.ee9a2543fcd6<br />
}}<br />
<br />
Please could this be included in the page.<br />
<br />
[[User:Garyvdm|Garyvdm]] ([[User talk:Garyvdm|talk]]) 09:03, 23 July 2013 (UTC)<br />
<br />
== shorten hg version ==<br />
<br />
To prevent long package file name,<br />
It is proper to use this format<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd $_repo<br />
_id=$(hg identify -i)<br />
echo $(hg identify -n).${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:30, 26 August 2013 (UTC)<br />
<br />
== fossil ==<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd local_repo<br />
_id=$(cat manifest.uuid 2>/dev/null)<br />
echo ${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:36, 26 August 2013 (UTC)<br />
<br />
== Locking ==<br />
<br />
Re [https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=364087&oldid=364032], I hope I wasn't the straw that broke the camel's back. I still fail to see why the Git section should be that large though, also in comparison to the other sections. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:26, 6 March 2015 (UTC)<br />
<br />
== set -o pipefail ==<br />
<br />
[https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=prev&oldid=363918 This change] mentioned {{ic|set -o ...}} as one of the reasons for reverting, nevertheless one example using {{ic|set -o pipefail}} still remains: [[VCS_package_guidelines#Git]] (the last example in that section). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:41, 6 March 2015 (UTC)<br />
<br />
== Guidelines on updating version numbers ==<br />
<br />
There are a few version control AUR packages out there which use the correct combined format of release and git commit. However, sometimes the maintainers refuse to update the default pkgver upon new releases of the software, stating that it's unnecessary since it's updated automatically during installation anyway. While this is true, I personally feel it should still be the maintainer's responsibility to update the default pkgver upon actual releases (not individual commits) as otherwise a user will never receive an automatic update and instead has to force-reinstall all(!) such packages regularly.<br />
<br />
Should we add this to the guidelines or how do others feel about this?<br />
<br />
{{unsigned|09:51, 10 September 2015|Airblader}}<br />
<br />
:There's no official update mechanism for AUR packages, so this argument only applies to those using unofficial [[AUR helpers]]. Otherwise there's soname bumps; if the package is a library, then pkgver should likely be updated. If it is a library the package depends ''on'', I don't know of a reliable way as pkg''rel'' is stuck to 1 on VCS packages. After all, a soname bump could happen between releases or even commits. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:00, 10 September 2015 (UTC)<br />
<br />
:If you're using a VCS package, you should be paying attention to what is happening upstream and choose when you rebuild the package. Managing them the same way as release packages makes no sense.<br />
:[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:25, 10 September 2015 (UTC)<br />
<br />
::Can you explain why it doesn't make sense to manage them the same way? One example is the package i3-git. As of writing this, it's version in the AUR is 4.10.2-xxxxx. The current i3 release is 4.10.4. So why *shouldn't* the package maintainer feel responsible to update it to 4.10.4-xxxxx? It's part of the Arch "feel" to be close to current development of software and I feel that if you maintain a package, you are responsible to update its version even if the actual installation process doesn't change. Sure I can rebuild my git packages, but that's really time intensive. I also cannot monitor all of those packages upstream with reasonable effort. This is exactly what a package management system has version numbers for and keeping them up to date is exactly what package maintainers are for, IMHO. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 11:39, 11 September 2015 (UTC)<br />
<br />
:::VCS packages will ''always'' build the latest revision, regardless of what pkgver on the AUR contains. If a package maintainer bumps pkgver of a VCS package, there is no assurance that the users will actually build the same (working) revision, hence the bumping makes no sense. If you need to track multiple git repos, use something like [https://github.com/kynikos/repocheck repocheck] to find out if you actually ''need'' to rebuild the package. I'm sure there are similar tools for other VCS, or just write your own. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:13, 11 September 2015 (UTC)<br />
<br />
::::I don't think that bumping makes no sense just because you build the latest version and not the one stated by pkgver. This is *always* the case, even if the version isn't bumped. The bump isn't meant to build exactly that version, it is meant to trigger an automatic update in the user's package management system that doesn't require checking out the repository and verifying it themselves. Again, IMHO this is what version numbers are for. If we don't care about such packages triggering an update or having any kind of comparable version number, what's the point in even giving them a (meaningful) number? We might as well just set pkgver=1 and be done with it, no? So why all the fancy pkgver() functions for VCS packages? I don't see how the repocheck you linked to is relevant for this. I don't have the repositories of my VCS packages laying around (only in /tmp right after I update them and only until I reboot). I'd like to approach this with a pragmatic argument: I hope we can agree that triggering the update for official releases of the package is some benefit. Given that, what's the *harm* in recommending to update pkgver? If there's an opinion that it makes no sense, that's one thing, but as long as it doesn't harm I think the small benefit sounds like reason enough to me. It's not like updating the pkgver of a package is difficult work. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 13:20, 11 September 2015 (UTC)<br />
<br />
:::::"I hope we can agree that triggering the update for official releases of the package is some benefit." We can't. I really see no benefit there at all. "Given that, what's the *harm* in recommending to update pkgver?" The harm comes from annoying people using those AUR helpers you mentioned. They have correctly chosen when they want to rebuild that package, now their helper is complaining all of the time even though they don't want to rebuild right now. Trigger automatic rebuilds of VCS packages is rarely a good thing, as there are no upsides and real downsides.<br />
:::::Your argument that it is really time intensive to rebuild your VCS packages makes no sense here, as you have to rebuild them either way. If you're unable to monitor upstream, why are you using a VCS package anyway? If you have no idea what's going on, you have no idea what you're getting when you build/rebuild it.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:38, 11 September 2015 (UTC)<br />
<br />
::::::I don't think that you choose VCS packages because you don't want your package management system to annoy you with updates. If that's something you don't want, then you don't use one at all (why would I choose to not receive updates for *that one* package, but for all 500 others?). IMHO, you choose VCS packages because you want to be close to current development, either "just because" or because you need(ed) it for something else. Also, sometimes there just is *only* the VCS version and no package for the release. Also, if you don't want to receive updates about a certain package, you can always ignore it in the config. I don't think it's good to deny *all* users the notification of updates just because *some* might not want them. <br />
::::::I also can't agree with "triggering automatic rebuilds of VCS packages is rarely a good thing". I never see upront what I actually build, so there's always that "risk". You don't install VCS packages if you want the release version. Furthermore, in practice, it seems rare that rebuilding a VCS package causes any issues since they usually point to the master branches which in most projects have some QA before merging.<br />
::::::Your point about having to rebuild them anyway and hence not saving time is not correct. You're arguing that I should just rebuild all VCS packages all the time just in case there was an update. I'm suggesting the information whether a package needs to be rebuilt is transported in the pkgver. This saves a *drastic* amount of time as I'm not speculating. Of course I can check the Github page of each package's upstream URL before rebuilding it, but this puts the work of versioning the package onto each and every user rather than the package maintainer. Again, if this is the desired behavior, we should recommend that VCS packages just set pkgver=1. I don't see why they need to provide any version info if it's completely unnecessary that it ever be updated. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 13:48, 11 September 2015 (UTC)<br />
:::::::"I'm suggesting the information whether a package needs to be rebuilt is transported in the pkgver." This is really the heart of the matter. This is completely and totally wrong for VCS packages. Whether the package needs a rebuild is up to your judgement, not the pkgver.<br />
:::::::There's nothing wrong with setting pkgver=1 (unless the actual version is less than 1). Some AUR package already do this, using "LATEST". The important thing is that the correct pkgver appears on the build package.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:59, 11 September 2015 (UTC)<br />
::::::::I just don't agree that it's "completely and totally" wrong. Yeah, sure, I can always decide to rebuild it myself. No one is taking this option away from anybody. But setting the pkgver when the actual release changes means the user is notified of this without having to care about it themselves (all n of them). Anyway, I don't think this is going anywhere. To me, letting the pkgver rot destroys a major point to why I use a package manager in the first place and makes me wonder why that person wants to be a package maintainer if they don't maintain the package, but clearly there's very different views on this. Thanks for the discussion anyway, at least I know now that there's no common view on it so there's no point in pushing for a change of guideline. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 22:58, 11 September 2015 (UTC)</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Talk:VCS_package_guidelines&diff=399408Talk:VCS package guidelines2015-09-11T13:48:57Z<p>Airblader: /* Guidelines on updating version numbers */</p>
<hr />
<div>== Numeric vs Date Standard in Git pkgver ==<br />
<br />
I'd like to see a standard emerge in AUR Git packages, but standards have to work down to the lowest common denominator. Only a small minority of GitHub projects properly tag their releases, so there can be only two LCD standards for Git packages: the Numeric standard, e.g. ("r1581.2b039da") and the Date standard, e.g. ("2014-01-01"). The date standard is much more readable, and actionable, and has the additional benefit of being backwards compatible with older Git packages.<br />
<br />
I don't know if any standard can emerge even if we wanted it to, but please allow me to at least add the Date standard to the VCS package guidelines wiki (as opposed to scrubbing it, :).<br />
<br />
:Using the commit date would be incorrect because it doesn't refer to a specific commit and the dates are not always sequential. It would be even more wrong if it was the build date, as that doesn't refer to anything to do with the version. -- [[User:thestinger|thestinger]] 21:33, 23 January 2015 (UTC)<br />
<br />
::''it doesn't refer to a specific commit''<br />
::<br />
::Neither does "r1581.2b039da" refer to a specific commit without the .git repo cmdline interaction, and it is considered best practice to prune $pkgdir of .git:<br />
::<br />
find "$pkgdir" -type d -name .git -exec rm -r '{}' +<br />
::<br />
::Can you explain what you mean by "the dates are not always sequential"? The Date standard looks like this:<br />
::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::<br />
::It displays the latest commit date from the upstream Git repo.<br />
::<br />
::In the edge case of breaking changes occurring upstream in Git repos on the same day, then package maintainers should increment pkgrel. In practice, "2014-01-01" is much more readable and useful than "r1581.2b039da". The readability benefits of "2014-01-01" vs. "r1581.2b039da" should not be underestimated due to edge cases. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 18:39, 24 January 2015 (UTC)<br />
:::A git commit id certainly refers to a specific commit. I don't know why you think this has anything to do with shipping the VCS repository in the package. The commit date of the most recent commit may be from 20 weeks ago while the earlier commits were from last week. Git does not have a linear history. It's not going to be changed to use a version format where it can go both backwards and forwards with no way of tracing it back to the commit. Readability is worthless if the information isn't meaningful... There are 2 hard requirements: newer revisions must have higher package versions without exceptions, and it must be possible to trace it back to a commit to properly identify and report bugs. -- [[User:thestinger|thestinger]] 18:53, 24 January 2015<br />
:::<br />
::::<br />
::::I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.<br />
::::<br />
::::Can you show me where to find "r1581.2b039da" on a GitHub/BitBucket repo? It doesn't exist anywhere that I can see. You need to have the repo locally, then cd into the Git repo and run:<br />
::::<br />
git rev-list --count HEAD<br />
::::<br />
::::That is work-intensive, and it conflicts with the best practice of pruning AUR packages of .git repos.<br />
::::<br />
::::I previously used the Wiki-recommended Numeric standard, so it's not like I haven't used it. I switched to the Date standard, updating hundreds of packages to reflect it. Why do you suppose that is?<br />
::::<br />
:::: ''Readability is worthless if the information isn't meaningful''<br />
::::You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581". I say this after maintaining for years, hundreds of Git packages in the AUR. You can tell by grepping `pacman -Q` exactly which AUR git packages are out of date with a two-second visit to GitHub. The Date standard is incredibly actionable and pragmatic not to mention simple and immediately understandable by anyone.<br />
::::<br />
:::: ''newer revisions must have higher package versions without exceptions''<br />
::::<br />
::::Not a problem: "2014-01-01" < "2014-01-02"<br />
::::<br />
:::: ''it must be possible to trace it back to a commit to properly identify and report bugs''<br />
::::<br />
:::: Given how frequently "stable" Go packages and C packages pull in Git dependencies as part of their build process without specifying a certain commit, I disagree with this proposition. Why would recording the version of acmedaemon as 1.5, when it pulls in Git packages without specifying commit ID, be all that different in bug reports than "2014-01-01"? In both cases, you will not be able to track down the exact cause of the bug by commit. In both cases, you will in all likelihood end up consulting the build date. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 03:32, 25 January 2015 (UTC)<br />
<br />
:::::''I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.''<br />
:::::In your scenerio, 2b039da is the short version of the commit hash and does point to a specific commit. As for where you find it on Github, it's listed on the commit log, of course. Just look at the right hand side of the page.<br />
:::::''You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581".''<br />
:::::In this case, human readability really is meaningless. Machine readability is all that matters.<br />
:::::''Not a problem: "2014-01-01" < "2014-01-02"''<br />
:::::And what happens when the commit after that is dated 2013-12-31? As thestinger pointed out, Git is not linear.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 03:40, 25 January 2015 (UTC)<br />
<br />
::::::''2b039da is the short version of the commit hash''<br />
::::::<br />
::::::Can this information be easily compared on GitHub to your local package version to check if it is out of date? The answer is no.<br />
::::::<br />
::::::It is not actionable, except by cloning the repo yourself, running the Git command, and then manually scanning the Git log for short versions. It's very work-intensive.<br />
::::::<br />
::::::''Git is not linear''<br />
::::::<br />
::::::Neither are stable packages on PyPi: https://pypi.python.org/pypi/tackpy/0.9.9a<br />
::::::<br />
::::::Pacman views the upgrade of 0.9.9 -> 0.9.9a as a downgrade. See https://aur.archlinux.org/packages/python2-tackpy for a real world example of this edge case. Edge cases should be no reason to prevent readers of the wiki to make informed choices about Git packaging standards. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:08, 25 January 2015 (UTC)<br />
<br />
:::::::Yes, the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page.<br />
:::::::As for PyPi's versioning scheme, their choice is different than what Arch's vercmp assumes. The packager needs to take this into account, just as all packagers must take upstream's idiosyncrasies into account. I don't see how it's relevant here.<br />
:::::::You also never answered my question, what happens when the last commit is dated before the commit previous to it? This question is critical, as it would cause your versioning scheme to go backwards by any and all measures. That makes it unacceptable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:15, 25 January 2015 (UTC)<br />
<br />
::::::::Incorrect.<br />
::::::::<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)<br />
::::::::<br />
::::::::The output of the above command does not correspond to any piece of information on GitHub.<br />
::::::::<br />
::::::::If PyPi packagers should take edge cases into account for PyPi packages, then they should do the same for Git packages. Edge cases aren't reason enough to scrub a competing standard from the wiki. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:23, 25 January 2015 (UTC)<br />
<br />
:::::::::I'm sorry if you can't find this information on GitHub. It's very, very plainly displayed in the places I already pointed you to. If you would take a minute to check instead of just jumping at me, you might find it.<br />
:::::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:31, 25 January 2015 (UTC)<br />
<br />
::::::::::''the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page''.<br />
::::::::::<br />
::::::::::This is (partially) incorrect. The short hash of each commit is not listed. What is listed in the commit log is the truncated commit ID.<br />
::::::::::<br />
::::::::::The revision count point I will retract. It didn't appear to work for my own Git repos, but that was because I ran the command from a Git subrepo (edge case :). The date still has the advantage of being more human readable than r1582. If a package has version 2011-10-22, I will know this project is either unmaintained, or it's been a really long time since I last rebuilt it. All without leaving the terminal. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:33, 25 January 2015 (UTC)<br />
<br />
::::::::::It's also very easy to look up or link to commits via the abbreviated commit hashes or proper identifiers produced by {{ic|git describe}}. -- [[User:thestinger|thestinger]] 04:33, 25 January 2015 (UTC)<br />
<br />
::::::That has nothing to do with non-linear history. It has to do with an incompatibility between Pacman's version comparison and the one chosen by the project. There are ways of dealing with that, but it has nothing to do with this discussion. -- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
:::::The ideal version is the one produced by {{ic|git describe}}, because it's easily understood by humans (last tag, commits since last tag, abbreviated commit), is also understood by the various Git commands and GitHub and is monotonically increasing thanks to the inclusion of the last version and revision count since then. The versions it produces ({{ic|10-7-g8537989}}) can be directly used with commands like {{ic|git show}}. Unlike the build date, it identifies a unique revision of the project, including the state of any submodules.<br />
<br />
:::::The only case where another method should be used is when the project doesn't yet have any tagged release or does the releases in a way that's not very sane. The releases ''should'' be tagged on master with additional tags in stable branches for fixes backported to old releases. If this isn't the case, the {{ic|git describe}} output needs to be emulated. A date is a poor way of doing that, because it's not connected to a specific point in the revision history.<br />
<br />
:::::The only case where the commit date would work is if Git is being used as a crippled centralized version control system. If all commits get created against master (no merging branches or patches) in a centralized repository where the system clock is never moved backwards, it could work... but that's not the reality of non-linear, distributed version control.<br />
<br />
:::::A build date is even worse, because it only refers to the local state of time and the local state of the repository. Commits from before that timestamp will often be pushed to the repository.<br />
<br />
:::::-- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
::::::A packaging standard must be compatible with the lowest common denominator. A minority of Git repos are properly tagged. The Date works as a standard, tags do not.<br />
::::::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::::::<br />
::::::The output of the above command shows the date of the most recent commit. If the most recent commit date happens to come before the date of a previous commit, I do understand this is suboptimal, but I consider it an edge case. Even in big projects with contributors in different time zones you will typically see branches merged in with PRs. PRs reset the date to something recent. The linearity of Git is rarely problematic, but I do see where you're coming from (I'm also a happy user of archversion for keeping packages up to date, though archversion works with the Date standard too :) --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:59, 25 January 2015 (UTC)<br />
<br />
:::::::The {{ic|git describe}} versioning system is the standard defined and used by Git itself. The dashes need to be converted into dots for {{ic|pkgver}} and an {{ic|r}} ''may'' be inserted to make it clearer which part is the revision number. If version-based tags on master are available, this is the only sane way to do it.<br />
<br />
:::::::Git defaults to fast-forwarding / applying patches without merge commits, as long as there are no conflicts. GitHub will ''always'' generate a merge commit but that's not true for anything applied / merged by the developers and then pushed to master. -- [[User:thestinger|thestinger]] 05:24, 25 January 2015 (UTC)<br />
<br />
:::::::You've made the claim that most git repos aren't properly tagged, not only now but to me previously. Do you have anything to back that up? IME, the large majority of projects that are in a usable state are either tagged or get tagged as they become stable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 05:27, 25 January 2015 (UTC)<br />
<br />
::::::::OK:<br />
::::::::<br />
git init<br />
::::::::<br />
::::::::You now have your very own untagged Git repo :).<br />
::::::::<br />
::::::::The majority of Git repos are untagged. If you want to have a standard compatible with the lowest common denominator, by definition you cannot depend on tags being there.<br />
::::::::<br />
::::::::I regularly package Git software in the alpha stages and software maintained by people who are unfamiliar with tagging or aren't bothered to tag. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:15, 25 January 2015 (UTC)<br />
<br />
::::As suggested in [[VCS package guidelines#Fallback]], I think the only date that can be used is the build date: for example I've recently used it in [https://aur.archlinux.org/packages/te/textadept-common-git/PKGBUILD a PKGBUILD] for a repo without tags or branches, also appending the first 7 characters of the commit hash (the repo is not cloned, so I could only use ''git-ls-remote''). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:30, 25 January 2015 (UTC)<br />
<br />
== Updating a CVS repo ==<br />
<br />
I don't use cvs. How can you describe the pkgver for cvs (for pacman 4.1)? <br><br />
-- [[User:Dracorp|Dracorp]] ([[User talk:Dracorp|talk]]) 09:31, 6 April 2013 (UTC)<br />
<br />
:CVS is not supported in pacman 4.1 like the other VCS tools. You will need to update pkgver manually until CVS support is added.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 22:44, 15 April 2013 (UTC)<br />
<br />
::Yeah, but how about mentioning that in the article (as well as giving a download example)? Even if it's not that common anymore.<br />
::--[[User:Det|Det]] ([[User talk:Det|talk]]) 22:39, 2 May 2013 (UTC)<br />
<br />
:::The download example can still be found in {{ic|/usr/share/pacman/}}. The next version of the ABS package should update it a bit so the download happens in the prepare function where it belongs. As for pkgver, I think the generic example using date covers that, as there's not a way to get a version number from a CVS repo. Maybe a note to that effect?<br />
::: -- [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 07:17, 15 May 2013 (UTC)<br />
<br />
::::That makes the most sense, but it might also be a good idea to rename the [[VCS PKGBUILD Guidelines#Fallback|"Fallback"]] section to something like "Fallback / CVS" to make it more obvious even when you're just checking out the table of contents.<br />
<br />
::::But as for ABS, as far as I can tell the last commit was over [https://projects.archlinux.org/abs.git/log/ 8 months] ago.<br />
::::--[[User:Det|Det]] ([[User talk:Det|talk]]) 05:54, 19 May 2013 (UTC)<br />
<br />
:::::Hmm, there were a number of patches submitted last month for cleaning up the prototypes, looks like none have been committed yet. I do remember a discussion (IRC maybe?) questioning the proper place for the prototypes, so maybe that's why? Looking at the patches, I was mistaken anyway; they didn't update the darcs or cvs prototypes. Simple enough, I'll send in a patch myself.<br />
:::::--[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 08:22, 19 May 2013 (UTC)<br />
<br />
: I use this dirty hack: {{ic|<nowiki>cvs history -c -a | cut -d' ' -f2 | sort -u | tail -n 1 | sed 's|-||g"</nowiki>}} ; could probably be improved.<br />
:--[[User:Buhman|Buhman]] ([[User talk:Buhman|talk]]) 18:00, 6 June 2013 (UTC)<br />
<br />
<br />
== pkgver function for hg based on tags ==<br />
<br />
I recent came across a way with hg to show the most recent tag, as well as the number of commits from this tag (similar to the output of {{ic|git describe}}.) <br />
<br />
{{hc|<nowiki>pkgver() {<br />
cd local_repo<br />
hg log -r . --template '{latesttag}.{latesttagdistance}.{node|short}\n'<br />
}</nowiki>|<br />
3.0.1.40.ee9a2543fcd6<br />
}}<br />
<br />
Please could this be included in the page.<br />
<br />
[[User:Garyvdm|Garyvdm]] ([[User talk:Garyvdm|talk]]) 09:03, 23 July 2013 (UTC)<br />
<br />
== shorten hg version ==<br />
<br />
To prevent long package file name,<br />
It is proper to use this format<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd $_repo<br />
_id=$(hg identify -i)<br />
echo $(hg identify -n).${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:30, 26 August 2013 (UTC)<br />
<br />
== fossil ==<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd local_repo<br />
_id=$(cat manifest.uuid 2>/dev/null)<br />
echo ${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:36, 26 August 2013 (UTC)<br />
<br />
== Locking ==<br />
<br />
Re [https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=364087&oldid=364032], I hope I wasn't the straw that broke the camel's back. I still fail to see why the Git section should be that large though, also in comparison to the other sections. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:26, 6 March 2015 (UTC)<br />
<br />
== set -o pipefail ==<br />
<br />
[https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=prev&oldid=363918 This change] mentioned {{ic|set -o ...}} as one of the reasons for reverting, nevertheless one example using {{ic|set -o pipefail}} still remains: [[VCS_package_guidelines#Git]] (the last example in that section). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:41, 6 March 2015 (UTC)<br />
<br />
== Guidelines on updating version numbers ==<br />
<br />
There are a few version control AUR packages out there which use the correct combined format of release and git commit. However, sometimes the maintainers refuse to update the default pkgver upon new releases of the software, stating that it's unnecessary since it's updated automatically during installation anyway. While this is true, I personally feel it should still be the maintainer's responsibility to update the default pkgver upon actual releases (not individual commits) as otherwise a user will never receive an automatic update and instead has to force-reinstall all(!) such packages regularly.<br />
<br />
Should we add this to the guidelines or how do others feel about this?<br />
<br />
{{unsigned|09:51, 10 September 2015|Airblader}}<br />
<br />
:There's no official update mechanism for AUR packages, so this argument only applies to those using unofficial [[AUR helpers]]. Otherwise there's soname bumps; if the package is a library, then pkgver should likely be updated. If it is a library the package depends ''on'', I don't know of a reliable way as pkg''rel'' is stuck to 1 on VCS packages. After all, a soname bump could happen between releases or even commits. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:00, 10 September 2015 (UTC)<br />
<br />
:If you're using a VCS package, you should be paying attention to what is happening upstream and choose when you rebuild the package. Managing them the same way as release packages makes no sense.<br />
:[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:25, 10 September 2015 (UTC)<br />
<br />
::Can you explain why it doesn't make sense to manage them the same way? One example is the package i3-git. As of writing this, it's version in the AUR is 4.10.2-xxxxx. The current i3 release is 4.10.4. So why *shouldn't* the package maintainer feel responsible to update it to 4.10.4-xxxxx? It's part of the Arch "feel" to be close to current development of software and I feel that if you maintain a package, you are responsible to update its version even if the actual installation process doesn't change. Sure I can rebuild my git packages, but that's really time intensive. I also cannot monitor all of those packages upstream with reasonable effort. This is exactly what a package management system has version numbers for and keeping them up to date is exactly what package maintainers are for, IMHO. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 11:39, 11 September 2015 (UTC)<br />
<br />
:::VCS packages will ''always'' build the latest revision, regardless of what pkgver on the AUR contains. If a package maintainer bumps pkgver of a VCS package, there is no assurance that the users will actually build the same (working) revision, hence the bumping makes no sense. If you need to track multiple git repos, use something like [https://github.com/kynikos/repocheck repocheck] to find out if you actually ''need'' to rebuild the package. I'm sure there are similar tools for other VCS, or just write your own. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:13, 11 September 2015 (UTC)<br />
<br />
::::I don't think that bumping makes no sense just because you build the latest version and not the one stated by pkgver. This is *always* the case, even if the version isn't bumped. The bump isn't meant to build exactly that version, it is meant to trigger an automatic update in the user's package management system that doesn't require checking out the repository and verifying it themselves. Again, IMHO this is what version numbers are for. If we don't care about such packages triggering an update or having any kind of comparable version number, what's the point in even giving them a (meaningful) number? We might as well just set pkgver=1 and be done with it, no? So why all the fancy pkgver() functions for VCS packages? I don't see how the repocheck you linked to is relevant for this. I don't have the repositories of my VCS packages laying around (only in /tmp right after I update them and only until I reboot). I'd like to approach this with a pragmatic argument: I hope we can agree that triggering the update for official releases of the package is some benefit. Given that, what's the *harm* in recommending to update pkgver? If there's an opinion that it makes no sense, that's one thing, but as long as it doesn't harm I think the small benefit sounds like reason enough to me. It's not like updating the pkgver of a package is difficult work. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 13:20, 11 September 2015 (UTC)<br />
<br />
:::::"I hope we can agree that triggering the update for official releases of the package is some benefit." We can't. I really see no benefit there at all. "Given that, what's the *harm* in recommending to update pkgver?" The harm comes from annoying people using those AUR helpers you mentioned. They have correctly chosen when they want to rebuild that package, now their helper is complaining all of the time even though they don't want to rebuild right now. Trigger automatic rebuilds of VCS packages is rarely a good thing, as there are no upsides and real downsides.<br />
:::::Your argument that it is really time intensive to rebuild your VCS packages makes no sense here, as you have to rebuild them either way. If you're unable to monitor upstream, why are you using a VCS package anyway? If you have no idea what's going on, you have no idea what you're getting when you build/rebuild it.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:38, 11 September 2015 (UTC)<br />
<br />
::::::I don't think that you choose VCS packages because you don't want your package management system to annoy you with updates. If that's something you don't want, then you don't use one at all (why would I choose to not receive updates for *that one* package, but for all 500 others?). IMHO, you choose VCS packages because you want to be close to current development, either "just because" or because you need(ed) it for something else. Also, sometimes there just is *only* the VCS version and no package for the release. Also, if you don't want to receive updates about a certain package, you can always ignore it in the config. I don't think it's good to deny *all* users the notification of updates just because *some* might not want them. <br />
::::::I also can't agree with "triggering automatic rebuilds of VCS packages is rarely a good thing". I never see upront what I actually build, so there's always that "risk". You don't install VCS packages if you want the release version. Furthermore, in practice, it seems rare that rebuilding a VCS package causes any issues since they usually point to the master branches which in most projects have some QA before merging.<br />
::::::Your point about having to rebuild them anyway and hence not saving time is not correct. You're arguing that I should just rebuild all VCS packages all the time just in case there was an update. I'm suggesting the information whether a package needs to be rebuilt is transported in the pkgver. This saves a *drastic* amount of time as I'm not speculating. Of course I can check the Github page of each package's upstream URL before rebuilding it, but this puts the work of versioning the package onto each and every user rather than the package maintainer. Again, if this is the desired behavior, we should recommend that VCS packages just set pkgver=1. I don't see why they need to provide any version info if it's completely unnecessary that it ever be updated. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 13:48, 11 September 2015 (UTC)</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Talk:VCS_package_guidelines&diff=399397Talk:VCS package guidelines2015-09-11T13:20:32Z<p>Airblader: /* Guidelines on updating version numbers */</p>
<hr />
<div>== Numeric vs Date Standard in Git pkgver ==<br />
<br />
I'd like to see a standard emerge in AUR Git packages, but standards have to work down to the lowest common denominator. Only a small minority of GitHub projects properly tag their releases, so there can be only two LCD standards for Git packages: the Numeric standard, e.g. ("r1581.2b039da") and the Date standard, e.g. ("2014-01-01"). The date standard is much more readable, and actionable, and has the additional benefit of being backwards compatible with older Git packages.<br />
<br />
I don't know if any standard can emerge even if we wanted it to, but please allow me to at least add the Date standard to the VCS package guidelines wiki (as opposed to scrubbing it, :).<br />
<br />
:Using the commit date would be incorrect because it doesn't refer to a specific commit and the dates are not always sequential. It would be even more wrong if it was the build date, as that doesn't refer to anything to do with the version. -- [[User:thestinger|thestinger]] 21:33, 23 January 2015 (UTC)<br />
<br />
::''it doesn't refer to a specific commit''<br />
::<br />
::Neither does "r1581.2b039da" refer to a specific commit without the .git repo cmdline interaction, and it is considered best practice to prune $pkgdir of .git:<br />
::<br />
find "$pkgdir" -type d -name .git -exec rm -r '{}' +<br />
::<br />
::Can you explain what you mean by "the dates are not always sequential"? The Date standard looks like this:<br />
::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::<br />
::It displays the latest commit date from the upstream Git repo.<br />
::<br />
::In the edge case of breaking changes occurring upstream in Git repos on the same day, then package maintainers should increment pkgrel. In practice, "2014-01-01" is much more readable and useful than "r1581.2b039da". The readability benefits of "2014-01-01" vs. "r1581.2b039da" should not be underestimated due to edge cases. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 18:39, 24 January 2015 (UTC)<br />
:::A git commit id certainly refers to a specific commit. I don't know why you think this has anything to do with shipping the VCS repository in the package. The commit date of the most recent commit may be from 20 weeks ago while the earlier commits were from last week. Git does not have a linear history. It's not going to be changed to use a version format where it can go both backwards and forwards with no way of tracing it back to the commit. Readability is worthless if the information isn't meaningful... There are 2 hard requirements: newer revisions must have higher package versions without exceptions, and it must be possible to trace it back to a commit to properly identify and report bugs. -- [[User:thestinger|thestinger]] 18:53, 24 January 2015<br />
:::<br />
::::<br />
::::I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.<br />
::::<br />
::::Can you show me where to find "r1581.2b039da" on a GitHub/BitBucket repo? It doesn't exist anywhere that I can see. You need to have the repo locally, then cd into the Git repo and run:<br />
::::<br />
git rev-list --count HEAD<br />
::::<br />
::::That is work-intensive, and it conflicts with the best practice of pruning AUR packages of .git repos.<br />
::::<br />
::::I previously used the Wiki-recommended Numeric standard, so it's not like I haven't used it. I switched to the Date standard, updating hundreds of packages to reflect it. Why do you suppose that is?<br />
::::<br />
:::: ''Readability is worthless if the information isn't meaningful''<br />
::::You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581". I say this after maintaining for years, hundreds of Git packages in the AUR. You can tell by grepping `pacman -Q` exactly which AUR git packages are out of date with a two-second visit to GitHub. The Date standard is incredibly actionable and pragmatic not to mention simple and immediately understandable by anyone.<br />
::::<br />
:::: ''newer revisions must have higher package versions without exceptions''<br />
::::<br />
::::Not a problem: "2014-01-01" < "2014-01-02"<br />
::::<br />
:::: ''it must be possible to trace it back to a commit to properly identify and report bugs''<br />
::::<br />
:::: Given how frequently "stable" Go packages and C packages pull in Git dependencies as part of their build process without specifying a certain commit, I disagree with this proposition. Why would recording the version of acmedaemon as 1.5, when it pulls in Git packages without specifying commit ID, be all that different in bug reports than "2014-01-01"? In both cases, you will not be able to track down the exact cause of the bug by commit. In both cases, you will in all likelihood end up consulting the build date. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 03:32, 25 January 2015 (UTC)<br />
<br />
:::::''I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.''<br />
:::::In your scenerio, 2b039da is the short version of the commit hash and does point to a specific commit. As for where you find it on Github, it's listed on the commit log, of course. Just look at the right hand side of the page.<br />
:::::''You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581".''<br />
:::::In this case, human readability really is meaningless. Machine readability is all that matters.<br />
:::::''Not a problem: "2014-01-01" < "2014-01-02"''<br />
:::::And what happens when the commit after that is dated 2013-12-31? As thestinger pointed out, Git is not linear.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 03:40, 25 January 2015 (UTC)<br />
<br />
::::::''2b039da is the short version of the commit hash''<br />
::::::<br />
::::::Can this information be easily compared on GitHub to your local package version to check if it is out of date? The answer is no.<br />
::::::<br />
::::::It is not actionable, except by cloning the repo yourself, running the Git command, and then manually scanning the Git log for short versions. It's very work-intensive.<br />
::::::<br />
::::::''Git is not linear''<br />
::::::<br />
::::::Neither are stable packages on PyPi: https://pypi.python.org/pypi/tackpy/0.9.9a<br />
::::::<br />
::::::Pacman views the upgrade of 0.9.9 -> 0.9.9a as a downgrade. See https://aur.archlinux.org/packages/python2-tackpy for a real world example of this edge case. Edge cases should be no reason to prevent readers of the wiki to make informed choices about Git packaging standards. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:08, 25 January 2015 (UTC)<br />
<br />
:::::::Yes, the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page.<br />
:::::::As for PyPi's versioning scheme, their choice is different than what Arch's vercmp assumes. The packager needs to take this into account, just as all packagers must take upstream's idiosyncrasies into account. I don't see how it's relevant here.<br />
:::::::You also never answered my question, what happens when the last commit is dated before the commit previous to it? This question is critical, as it would cause your versioning scheme to go backwards by any and all measures. That makes it unacceptable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:15, 25 January 2015 (UTC)<br />
<br />
::::::::Incorrect.<br />
::::::::<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)<br />
::::::::<br />
::::::::The output of the above command does not correspond to any piece of information on GitHub.<br />
::::::::<br />
::::::::If PyPi packagers should take edge cases into account for PyPi packages, then they should do the same for Git packages. Edge cases aren't reason enough to scrub a competing standard from the wiki. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:23, 25 January 2015 (UTC)<br />
<br />
:::::::::I'm sorry if you can't find this information on GitHub. It's very, very plainly displayed in the places I already pointed you to. If you would take a minute to check instead of just jumping at me, you might find it.<br />
:::::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:31, 25 January 2015 (UTC)<br />
<br />
::::::::::''the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page''.<br />
::::::::::<br />
::::::::::This is (partially) incorrect. The short hash of each commit is not listed. What is listed in the commit log is the truncated commit ID.<br />
::::::::::<br />
::::::::::The revision count point I will retract. It didn't appear to work for my own Git repos, but that was because I ran the command from a Git subrepo (edge case :). The date still has the advantage of being more human readable than r1582. If a package has version 2011-10-22, I will know this project is either unmaintained, or it's been a really long time since I last rebuilt it. All without leaving the terminal. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:33, 25 January 2015 (UTC)<br />
<br />
::::::::::It's also very easy to look up or link to commits via the abbreviated commit hashes or proper identifiers produced by {{ic|git describe}}. -- [[User:thestinger|thestinger]] 04:33, 25 January 2015 (UTC)<br />
<br />
::::::That has nothing to do with non-linear history. It has to do with an incompatibility between Pacman's version comparison and the one chosen by the project. There are ways of dealing with that, but it has nothing to do with this discussion. -- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
:::::The ideal version is the one produced by {{ic|git describe}}, because it's easily understood by humans (last tag, commits since last tag, abbreviated commit), is also understood by the various Git commands and GitHub and is monotonically increasing thanks to the inclusion of the last version and revision count since then. The versions it produces ({{ic|10-7-g8537989}}) can be directly used with commands like {{ic|git show}}. Unlike the build date, it identifies a unique revision of the project, including the state of any submodules.<br />
<br />
:::::The only case where another method should be used is when the project doesn't yet have any tagged release or does the releases in a way that's not very sane. The releases ''should'' be tagged on master with additional tags in stable branches for fixes backported to old releases. If this isn't the case, the {{ic|git describe}} output needs to be emulated. A date is a poor way of doing that, because it's not connected to a specific point in the revision history.<br />
<br />
:::::The only case where the commit date would work is if Git is being used as a crippled centralized version control system. If all commits get created against master (no merging branches or patches) in a centralized repository where the system clock is never moved backwards, it could work... but that's not the reality of non-linear, distributed version control.<br />
<br />
:::::A build date is even worse, because it only refers to the local state of time and the local state of the repository. Commits from before that timestamp will often be pushed to the repository.<br />
<br />
:::::-- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
::::::A packaging standard must be compatible with the lowest common denominator. A minority of Git repos are properly tagged. The Date works as a standard, tags do not.<br />
::::::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::::::<br />
::::::The output of the above command shows the date of the most recent commit. If the most recent commit date happens to come before the date of a previous commit, I do understand this is suboptimal, but I consider it an edge case. Even in big projects with contributors in different time zones you will typically see branches merged in with PRs. PRs reset the date to something recent. The linearity of Git is rarely problematic, but I do see where you're coming from (I'm also a happy user of archversion for keeping packages up to date, though archversion works with the Date standard too :) --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:59, 25 January 2015 (UTC)<br />
<br />
:::::::The {{ic|git describe}} versioning system is the standard defined and used by Git itself. The dashes need to be converted into dots for {{ic|pkgver}} and an {{ic|r}} ''may'' be inserted to make it clearer which part is the revision number. If version-based tags on master are available, this is the only sane way to do it.<br />
<br />
:::::::Git defaults to fast-forwarding / applying patches without merge commits, as long as there are no conflicts. GitHub will ''always'' generate a merge commit but that's not true for anything applied / merged by the developers and then pushed to master. -- [[User:thestinger|thestinger]] 05:24, 25 January 2015 (UTC)<br />
<br />
:::::::You've made the claim that most git repos aren't properly tagged, not only now but to me previously. Do you have anything to back that up? IME, the large majority of projects that are in a usable state are either tagged or get tagged as they become stable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 05:27, 25 January 2015 (UTC)<br />
<br />
::::::::OK:<br />
::::::::<br />
git init<br />
::::::::<br />
::::::::You now have your very own untagged Git repo :).<br />
::::::::<br />
::::::::The majority of Git repos are untagged. If you want to have a standard compatible with the lowest common denominator, by definition you cannot depend on tags being there.<br />
::::::::<br />
::::::::I regularly package Git software in the alpha stages and software maintained by people who are unfamiliar with tagging or aren't bothered to tag. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:15, 25 January 2015 (UTC)<br />
<br />
::::As suggested in [[VCS package guidelines#Fallback]], I think the only date that can be used is the build date: for example I've recently used it in [https://aur.archlinux.org/packages/te/textadept-common-git/PKGBUILD a PKGBUILD] for a repo without tags or branches, also appending the first 7 characters of the commit hash (the repo is not cloned, so I could only use ''git-ls-remote''). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:30, 25 January 2015 (UTC)<br />
<br />
== Updating a CVS repo ==<br />
<br />
I don't use cvs. How can you describe the pkgver for cvs (for pacman 4.1)? <br><br />
-- [[User:Dracorp|Dracorp]] ([[User talk:Dracorp|talk]]) 09:31, 6 April 2013 (UTC)<br />
<br />
:CVS is not supported in pacman 4.1 like the other VCS tools. You will need to update pkgver manually until CVS support is added.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 22:44, 15 April 2013 (UTC)<br />
<br />
::Yeah, but how about mentioning that in the article (as well as giving a download example)? Even if it's not that common anymore.<br />
::--[[User:Det|Det]] ([[User talk:Det|talk]]) 22:39, 2 May 2013 (UTC)<br />
<br />
:::The download example can still be found in {{ic|/usr/share/pacman/}}. The next version of the ABS package should update it a bit so the download happens in the prepare function where it belongs. As for pkgver, I think the generic example using date covers that, as there's not a way to get a version number from a CVS repo. Maybe a note to that effect?<br />
::: -- [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 07:17, 15 May 2013 (UTC)<br />
<br />
::::That makes the most sense, but it might also be a good idea to rename the [[VCS PKGBUILD Guidelines#Fallback|"Fallback"]] section to something like "Fallback / CVS" to make it more obvious even when you're just checking out the table of contents.<br />
<br />
::::But as for ABS, as far as I can tell the last commit was over [https://projects.archlinux.org/abs.git/log/ 8 months] ago.<br />
::::--[[User:Det|Det]] ([[User talk:Det|talk]]) 05:54, 19 May 2013 (UTC)<br />
<br />
:::::Hmm, there were a number of patches submitted last month for cleaning up the prototypes, looks like none have been committed yet. I do remember a discussion (IRC maybe?) questioning the proper place for the prototypes, so maybe that's why? Looking at the patches, I was mistaken anyway; they didn't update the darcs or cvs prototypes. Simple enough, I'll send in a patch myself.<br />
:::::--[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 08:22, 19 May 2013 (UTC)<br />
<br />
: I use this dirty hack: {{ic|<nowiki>cvs history -c -a | cut -d' ' -f2 | sort -u | tail -n 1 | sed 's|-||g"</nowiki>}} ; could probably be improved.<br />
:--[[User:Buhman|Buhman]] ([[User talk:Buhman|talk]]) 18:00, 6 June 2013 (UTC)<br />
<br />
<br />
== pkgver function for hg based on tags ==<br />
<br />
I recent came across a way with hg to show the most recent tag, as well as the number of commits from this tag (similar to the output of {{ic|git describe}}.) <br />
<br />
{{hc|<nowiki>pkgver() {<br />
cd local_repo<br />
hg log -r . --template '{latesttag}.{latesttagdistance}.{node|short}\n'<br />
}</nowiki>|<br />
3.0.1.40.ee9a2543fcd6<br />
}}<br />
<br />
Please could this be included in the page.<br />
<br />
[[User:Garyvdm|Garyvdm]] ([[User talk:Garyvdm|talk]]) 09:03, 23 July 2013 (UTC)<br />
<br />
== shorten hg version ==<br />
<br />
To prevent long package file name,<br />
It is proper to use this format<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd $_repo<br />
_id=$(hg identify -i)<br />
echo $(hg identify -n).${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:30, 26 August 2013 (UTC)<br />
<br />
== fossil ==<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd local_repo<br />
_id=$(cat manifest.uuid 2>/dev/null)<br />
echo ${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:36, 26 August 2013 (UTC)<br />
<br />
== Locking ==<br />
<br />
Re [https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=364087&oldid=364032], I hope I wasn't the straw that broke the camel's back. I still fail to see why the Git section should be that large though, also in comparison to the other sections. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:26, 6 March 2015 (UTC)<br />
<br />
== set -o pipefail ==<br />
<br />
[https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=prev&oldid=363918 This change] mentioned {{ic|set -o ...}} as one of the reasons for reverting, nevertheless one example using {{ic|set -o pipefail}} still remains: [[VCS_package_guidelines#Git]] (the last example in that section). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:41, 6 March 2015 (UTC)<br />
<br />
== Guidelines on updating version numbers ==<br />
<br />
There are a few version control AUR packages out there which use the correct combined format of release and git commit. However, sometimes the maintainers refuse to update the default pkgver upon new releases of the software, stating that it's unnecessary since it's updated automatically during installation anyway. While this is true, I personally feel it should still be the maintainer's responsibility to update the default pkgver upon actual releases (not individual commits) as otherwise a user will never receive an automatic update and instead has to force-reinstall all(!) such packages regularly.<br />
<br />
Should we add this to the guidelines or how do others feel about this?<br />
<br />
{{unsigned|09:51, 10 September 2015|Airblader}}<br />
<br />
:There's no official update mechanism for AUR packages, so this argument only applies to those using unofficial [[AUR helpers]]. Otherwise there's soname bumps; if the package is a library, then pkgver should likely be updated. If it is a library the package depends ''on'', I don't know of a reliable way as pkg''rel'' is stuck to 1 on VCS packages. After all, a soname bump could happen between releases or even commits. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:00, 10 September 2015 (UTC)<br />
<br />
:If you're using a VCS package, you should be paying attention to what is happening upstream and choose when you rebuild the package. Managing them the same way as release packages makes no sense.<br />
:[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:25, 10 September 2015 (UTC)<br />
<br />
::Can you explain why it doesn't make sense to manage them the same way? One example is the package i3-git. As of writing this, it's version in the AUR is 4.10.2-xxxxx. The current i3 release is 4.10.4. So why *shouldn't* the package maintainer feel responsible to update it to 4.10.4-xxxxx? It's part of the Arch "feel" to be close to current development of software and I feel that if you maintain a package, you are responsible to update its version even if the actual installation process doesn't change. Sure I can rebuild my git packages, but that's really time intensive. I also cannot monitor all of those packages upstream with reasonable effort. This is exactly what a package management system has version numbers for and keeping them up to date is exactly what package maintainers are for, IMHO. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 11:39, 11 September 2015 (UTC)<br />
<br />
:::VCS packages will ''always'' build the latest revision, regardless of what pkgver on the AUR contains. If a package maintainer bumps pkgver of a VCS package, there is no assurance that the users will actually build the same (working) revision, hence the bumping makes no sense. If you need to track multiple git repos, use something like [https://github.com/kynikos/repocheck repocheck] to find out if you actually ''need'' to rebuild the package. I'm sure there are similar tools for other VCS, or just write your own. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:13, 11 September 2015 (UTC)<br />
<br />
::::I don't think that bumping makes no sense just because you build the latest version and not the one stated by pkgver. This is *always* the case, even if the version isn't bumped. The bump isn't meant to build exactly that version, it is meant to trigger an automatic update in the user's package management system that doesn't require checking out the repository and verifying it themselves. Again, IMHO this is what version numbers are for. If we don't care about such packages triggering an update or having any kind of comparable version number, what's the point in even giving them a (meaningful) number? We might as well just set pkgver=1 and be done with it, no? So why all the fancy pkgver() functions for VCS packages? I don't see how the repocheck you linked to is relevant for this. I don't have the repositories of my VCS packages laying around (only in /tmp right after I update them and only until I reboot). I'd like to approach this with a pragmatic argument: I hope we can agree that triggering the update for official releases of the package is some benefit. Given that, what's the *harm* in recommending to update pkgver? If there's an opinion that it makes no sense, that's one thing, but as long as it doesn't harm I think the small benefit sounds like reason enough to me. It's not like updating the pkgver of a package is difficult work. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 13:20, 11 September 2015 (UTC)</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Talk:VCS_package_guidelines&diff=399378Talk:VCS package guidelines2015-09-11T11:40:04Z<p>Airblader: /* Guidelines on updating version numbers */</p>
<hr />
<div>== Numeric vs Date Standard in Git pkgver ==<br />
<br />
I'd like to see a standard emerge in AUR Git packages, but standards have to work down to the lowest common denominator. Only a small minority of GitHub projects properly tag their releases, so there can be only two LCD standards for Git packages: the Numeric standard, e.g. ("r1581.2b039da") and the Date standard, e.g. ("2014-01-01"). The date standard is much more readable, and actionable, and has the additional benefit of being backwards compatible with older Git packages.<br />
<br />
I don't know if any standard can emerge even if we wanted it to, but please allow me to at least add the Date standard to the VCS package guidelines wiki (as opposed to scrubbing it, :).<br />
<br />
:Using the commit date would be incorrect because it doesn't refer to a specific commit and the dates are not always sequential. It would be even more wrong if it was the build date, as that doesn't refer to anything to do with the version. -- [[User:thestinger|thestinger]] 21:33, 23 January 2015 (UTC)<br />
<br />
::''it doesn't refer to a specific commit''<br />
::<br />
::Neither does "r1581.2b039da" refer to a specific commit without the .git repo cmdline interaction, and it is considered best practice to prune $pkgdir of .git:<br />
::<br />
find "$pkgdir" -type d -name .git -exec rm -r '{}' +<br />
::<br />
::Can you explain what you mean by "the dates are not always sequential"? The Date standard looks like this:<br />
::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::<br />
::It displays the latest commit date from the upstream Git repo.<br />
::<br />
::In the edge case of breaking changes occurring upstream in Git repos on the same day, then package maintainers should increment pkgrel. In practice, "2014-01-01" is much more readable and useful than "r1581.2b039da". The readability benefits of "2014-01-01" vs. "r1581.2b039da" should not be underestimated due to edge cases. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 18:39, 24 January 2015 (UTC)<br />
:::A git commit id certainly refers to a specific commit. I don't know why you think this has anything to do with shipping the VCS repository in the package. The commit date of the most recent commit may be from 20 weeks ago while the earlier commits were from last week. Git does not have a linear history. It's not going to be changed to use a version format where it can go both backwards and forwards with no way of tracing it back to the commit. Readability is worthless if the information isn't meaningful... There are 2 hard requirements: newer revisions must have higher package versions without exceptions, and it must be possible to trace it back to a commit to properly identify and report bugs. -- [[User:thestinger|thestinger]] 18:53, 24 January 2015<br />
:::<br />
::::<br />
::::I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.<br />
::::<br />
::::Can you show me where to find "r1581.2b039da" on a GitHub/BitBucket repo? It doesn't exist anywhere that I can see. You need to have the repo locally, then cd into the Git repo and run:<br />
::::<br />
git rev-list --count HEAD<br />
::::<br />
::::That is work-intensive, and it conflicts with the best practice of pruning AUR packages of .git repos.<br />
::::<br />
::::I previously used the Wiki-recommended Numeric standard, so it's not like I haven't used it. I switched to the Date standard, updating hundreds of packages to reflect it. Why do you suppose that is?<br />
::::<br />
:::: ''Readability is worthless if the information isn't meaningful''<br />
::::You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581". I say this after maintaining for years, hundreds of Git packages in the AUR. You can tell by grepping `pacman -Q` exactly which AUR git packages are out of date with a two-second visit to GitHub. The Date standard is incredibly actionable and pragmatic not to mention simple and immediately understandable by anyone.<br />
::::<br />
:::: ''newer revisions must have higher package versions without exceptions''<br />
::::<br />
::::Not a problem: "2014-01-01" < "2014-01-02"<br />
::::<br />
:::: ''it must be possible to trace it back to a commit to properly identify and report bugs''<br />
::::<br />
:::: Given how frequently "stable" Go packages and C packages pull in Git dependencies as part of their build process without specifying a certain commit, I disagree with this proposition. Why would recording the version of acmedaemon as 1.5, when it pulls in Git packages without specifying commit ID, be all that different in bug reports than "2014-01-01"? In both cases, you will not be able to track down the exact cause of the bug by commit. In both cases, you will in all likelihood end up consulting the build date. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 03:32, 25 January 2015 (UTC)<br />
<br />
:::::''I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.''<br />
:::::In your scenerio, 2b039da is the short version of the commit hash and does point to a specific commit. As for where you find it on Github, it's listed on the commit log, of course. Just look at the right hand side of the page.<br />
:::::''You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581".''<br />
:::::In this case, human readability really is meaningless. Machine readability is all that matters.<br />
:::::''Not a problem: "2014-01-01" < "2014-01-02"''<br />
:::::And what happens when the commit after that is dated 2013-12-31? As thestinger pointed out, Git is not linear.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 03:40, 25 January 2015 (UTC)<br />
<br />
::::::''2b039da is the short version of the commit hash''<br />
::::::<br />
::::::Can this information be easily compared on GitHub to your local package version to check if it is out of date? The answer is no.<br />
::::::<br />
::::::It is not actionable, except by cloning the repo yourself, running the Git command, and then manually scanning the Git log for short versions. It's very work-intensive.<br />
::::::<br />
::::::''Git is not linear''<br />
::::::<br />
::::::Neither are stable packages on PyPi: https://pypi.python.org/pypi/tackpy/0.9.9a<br />
::::::<br />
::::::Pacman views the upgrade of 0.9.9 -> 0.9.9a as a downgrade. See https://aur.archlinux.org/packages/python2-tackpy for a real world example of this edge case. Edge cases should be no reason to prevent readers of the wiki to make informed choices about Git packaging standards. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:08, 25 January 2015 (UTC)<br />
<br />
:::::::Yes, the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page.<br />
:::::::As for PyPi's versioning scheme, their choice is different than what Arch's vercmp assumes. The packager needs to take this into account, just as all packagers must take upstream's idiosyncrasies into account. I don't see how it's relevant here.<br />
:::::::You also never answered my question, what happens when the last commit is dated before the commit previous to it? This question is critical, as it would cause your versioning scheme to go backwards by any and all measures. That makes it unacceptable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:15, 25 January 2015 (UTC)<br />
<br />
::::::::Incorrect.<br />
::::::::<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)<br />
::::::::<br />
::::::::The output of the above command does not correspond to any piece of information on GitHub.<br />
::::::::<br />
::::::::If PyPi packagers should take edge cases into account for PyPi packages, then they should do the same for Git packages. Edge cases aren't reason enough to scrub a competing standard from the wiki. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:23, 25 January 2015 (UTC)<br />
<br />
:::::::::I'm sorry if you can't find this information on GitHub. It's very, very plainly displayed in the places I already pointed you to. If you would take a minute to check instead of just jumping at me, you might find it.<br />
:::::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:31, 25 January 2015 (UTC)<br />
<br />
::::::::::''the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page''.<br />
::::::::::<br />
::::::::::This is (partially) incorrect. The short hash of each commit is not listed. What is listed in the commit log is the truncated commit ID.<br />
::::::::::<br />
::::::::::The revision count point I will retract. It didn't appear to work for my own Git repos, but that was because I ran the command from a Git subrepo (edge case :). The date still has the advantage of being more human readable than r1582. If a package has version 2011-10-22, I will know this project is either unmaintained, or it's been a really long time since I last rebuilt it. All without leaving the terminal. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:33, 25 January 2015 (UTC)<br />
<br />
::::::::::It's also very easy to look up or link to commits via the abbreviated commit hashes or proper identifiers produced by {{ic|git describe}}. -- [[User:thestinger|thestinger]] 04:33, 25 January 2015 (UTC)<br />
<br />
::::::That has nothing to do with non-linear history. It has to do with an incompatibility between Pacman's version comparison and the one chosen by the project. There are ways of dealing with that, but it has nothing to do with this discussion. -- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
:::::The ideal version is the one produced by {{ic|git describe}}, because it's easily understood by humans (last tag, commits since last tag, abbreviated commit), is also understood by the various Git commands and GitHub and is monotonically increasing thanks to the inclusion of the last version and revision count since then. The versions it produces ({{ic|10-7-g8537989}}) can be directly used with commands like {{ic|git show}}. Unlike the build date, it identifies a unique revision of the project, including the state of any submodules.<br />
<br />
:::::The only case where another method should be used is when the project doesn't yet have any tagged release or does the releases in a way that's not very sane. The releases ''should'' be tagged on master with additional tags in stable branches for fixes backported to old releases. If this isn't the case, the {{ic|git describe}} output needs to be emulated. A date is a poor way of doing that, because it's not connected to a specific point in the revision history.<br />
<br />
:::::The only case where the commit date would work is if Git is being used as a crippled centralized version control system. If all commits get created against master (no merging branches or patches) in a centralized repository where the system clock is never moved backwards, it could work... but that's not the reality of non-linear, distributed version control.<br />
<br />
:::::A build date is even worse, because it only refers to the local state of time and the local state of the repository. Commits from before that timestamp will often be pushed to the repository.<br />
<br />
:::::-- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
::::::A packaging standard must be compatible with the lowest common denominator. A minority of Git repos are properly tagged. The Date works as a standard, tags do not.<br />
::::::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::::::<br />
::::::The output of the above command shows the date of the most recent commit. If the most recent commit date happens to come before the date of a previous commit, I do understand this is suboptimal, but I consider it an edge case. Even in big projects with contributors in different time zones you will typically see branches merged in with PRs. PRs reset the date to something recent. The linearity of Git is rarely problematic, but I do see where you're coming from (I'm also a happy user of archversion for keeping packages up to date, though archversion works with the Date standard too :) --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:59, 25 January 2015 (UTC)<br />
<br />
:::::::The {{ic|git describe}} versioning system is the standard defined and used by Git itself. The dashes need to be converted into dots for {{ic|pkgver}} and an {{ic|r}} ''may'' be inserted to make it clearer which part is the revision number. If version-based tags on master are available, this is the only sane way to do it.<br />
<br />
:::::::Git defaults to fast-forwarding / applying patches without merge commits, as long as there are no conflicts. GitHub will ''always'' generate a merge commit but that's not true for anything applied / merged by the developers and then pushed to master. -- [[User:thestinger|thestinger]] 05:24, 25 January 2015 (UTC)<br />
<br />
:::::::You've made the claim that most git repos aren't properly tagged, not only now but to me previously. Do you have anything to back that up? IME, the large majority of projects that are in a usable state are either tagged or get tagged as they become stable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 05:27, 25 January 2015 (UTC)<br />
<br />
::::::::OK:<br />
::::::::<br />
git init<br />
::::::::<br />
::::::::You now have your very own untagged Git repo :).<br />
::::::::<br />
::::::::The majority of Git repos are untagged. If you want to have a standard compatible with the lowest common denominator, by definition you cannot depend on tags being there.<br />
::::::::<br />
::::::::I regularly package Git software in the alpha stages and software maintained by people who are unfamiliar with tagging or aren't bothered to tag. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:15, 25 January 2015 (UTC)<br />
<br />
::::As suggested in [[VCS package guidelines#Fallback]], I think the only date that can be used is the build date: for example I've recently used it in [https://aur.archlinux.org/packages/te/textadept-common-git/PKGBUILD a PKGBUILD] for a repo without tags or branches, also appending the first 7 characters of the commit hash (the repo is not cloned, so I could only use ''git-ls-remote''). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:30, 25 January 2015 (UTC)<br />
<br />
== Updating a CVS repo ==<br />
<br />
I don't use cvs. How can you describe the pkgver for cvs (for pacman 4.1)? <br><br />
-- [[User:Dracorp|Dracorp]] ([[User talk:Dracorp|talk]]) 09:31, 6 April 2013 (UTC)<br />
<br />
:CVS is not supported in pacman 4.1 like the other VCS tools. You will need to update pkgver manually until CVS support is added.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 22:44, 15 April 2013 (UTC)<br />
<br />
::Yeah, but how about mentioning that in the article (as well as giving a download example)? Even if it's not that common anymore.<br />
::--[[User:Det|Det]] ([[User talk:Det|talk]]) 22:39, 2 May 2013 (UTC)<br />
<br />
:::The download example can still be found in {{ic|/usr/share/pacman/}}. The next version of the ABS package should update it a bit so the download happens in the prepare function where it belongs. As for pkgver, I think the generic example using date covers that, as there's not a way to get a version number from a CVS repo. Maybe a note to that effect?<br />
::: -- [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 07:17, 15 May 2013 (UTC)<br />
<br />
::::That makes the most sense, but it might also be a good idea to rename the [[VCS PKGBUILD Guidelines#Fallback|"Fallback"]] section to something like "Fallback / CVS" to make it more obvious even when you're just checking out the table of contents.<br />
<br />
::::But as for ABS, as far as I can tell the last commit was over [https://projects.archlinux.org/abs.git/log/ 8 months] ago.<br />
::::--[[User:Det|Det]] ([[User talk:Det|talk]]) 05:54, 19 May 2013 (UTC)<br />
<br />
:::::Hmm, there were a number of patches submitted last month for cleaning up the prototypes, looks like none have been committed yet. I do remember a discussion (IRC maybe?) questioning the proper place for the prototypes, so maybe that's why? Looking at the patches, I was mistaken anyway; they didn't update the darcs or cvs prototypes. Simple enough, I'll send in a patch myself.<br />
:::::--[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 08:22, 19 May 2013 (UTC)<br />
<br />
: I use this dirty hack: {{ic|<nowiki>cvs history -c -a | cut -d' ' -f2 | sort -u | tail -n 1 | sed 's|-||g"</nowiki>}} ; could probably be improved.<br />
:--[[User:Buhman|Buhman]] ([[User talk:Buhman|talk]]) 18:00, 6 June 2013 (UTC)<br />
<br />
<br />
== pkgver function for hg based on tags ==<br />
<br />
I recent came across a way with hg to show the most recent tag, as well as the number of commits from this tag (similar to the output of {{ic|git describe}}.) <br />
<br />
{{hc|<nowiki>pkgver() {<br />
cd local_repo<br />
hg log -r . --template '{latesttag}.{latesttagdistance}.{node|short}\n'<br />
}</nowiki>|<br />
3.0.1.40.ee9a2543fcd6<br />
}}<br />
<br />
Please could this be included in the page.<br />
<br />
[[User:Garyvdm|Garyvdm]] ([[User talk:Garyvdm|talk]]) 09:03, 23 July 2013 (UTC)<br />
<br />
== shorten hg version ==<br />
<br />
To prevent long package file name,<br />
It is proper to use this format<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd $_repo<br />
_id=$(hg identify -i)<br />
echo $(hg identify -n).${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:30, 26 August 2013 (UTC)<br />
<br />
== fossil ==<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd local_repo<br />
_id=$(cat manifest.uuid 2>/dev/null)<br />
echo ${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:36, 26 August 2013 (UTC)<br />
<br />
== Locking ==<br />
<br />
Re [https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=364087&oldid=364032], I hope I wasn't the straw that broke the camel's back. I still fail to see why the Git section should be that large though, also in comparison to the other sections. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:26, 6 March 2015 (UTC)<br />
<br />
== set -o pipefail ==<br />
<br />
[https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=prev&oldid=363918 This change] mentioned {{ic|set -o ...}} as one of the reasons for reverting, nevertheless one example using {{ic|set -o pipefail}} still remains: [[VCS_package_guidelines#Git]] (the last example in that section). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:41, 6 March 2015 (UTC)<br />
<br />
== Guidelines on updating version numbers ==<br />
<br />
There are a few version control AUR packages out there which use the correct combined format of release and git commit. However, sometimes the maintainers refuse to update the default pkgver upon new releases of the software, stating that it's unnecessary since it's updated automatically during installation anyway. While this is true, I personally feel it should still be the maintainer's responsibility to update the default pkgver upon actual releases (not individual commits) as otherwise a user will never receive an automatic update and instead has to force-reinstall all(!) such packages regularly.<br />
<br />
Should we add this to the guidelines or how do others feel about this?<br />
<br />
{{unsigned|09:51, 10 September 2015|Airblader}}<br />
<br />
:There's no official update mechanism for AUR packages, so this argument only applies to those using unofficial [[AUR helpers]]. Otherwise there's soname bumps; if the package is a library, then pkgver should likely be updated. If it is a library the package depends ''on'', I don't know of a reliable way as pkg''rel'' is stuck to 1 on VCS packages. After all, a soname bump could happen between releases or even commits. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:00, 10 September 2015 (UTC)<br />
<br />
:If you're using a VCS package, you should be paying attention to what is happening upstream and choose when you rebuild the package. Managing them the same way as release packages makes no sense.<br />
:[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 13:25, 10 September 2015 (UTC)<br />
<br />
::Can you explain why it doesn't make sense to manage them the same way? One example is the package i3-git. As of writing this, it's version in the AUR is 4.10.2-xxxxx. The current i3 release is 4.10.4. So why *shouldn't* the package maintainer feel responsible to update it to 4.10.4-xxxxx? It's part of the Arch "feel" to be close to current development of software and I feel that if you maintain a package, you are responsible to update its version even if the actual installation process doesn't change. Sure I can rebuild my git packages, but that's really time intensive. I also cannot monitor all of those packages upstream with reasonable effort. This is exactly what a package management system has version numbers for and keeping them up to date is exactly what package maintainers are for, IMHO. [[User:Airblader|Airblader]] ([[User talk:Airblader|talk]]) 11:39, 11 September 2015 (UTC)</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Talk:VCS_package_guidelines&diff=399197Talk:VCS package guidelines2015-09-10T09:51:13Z<p>Airblader: /* Guidelines on updating version numbers */ new section</p>
<hr />
<div>== Numeric vs Date Standard in Git pkgver ==<br />
<br />
I'd like to see a standard emerge in AUR Git packages, but standards have to work down to the lowest common denominator. Only a small minority of GitHub projects properly tag their releases, so there can be only two LCD standards for Git packages: the Numeric standard, e.g. ("r1581.2b039da") and the Date standard, e.g. ("2014-01-01"). The date standard is much more readable, and actionable, and has the additional benefit of being backwards compatible with older Git packages.<br />
<br />
I don't know if any standard can emerge even if we wanted it to, but please allow me to at least add the Date standard to the VCS package guidelines wiki (as opposed to scrubbing it, :).<br />
<br />
:Using the commit date would be incorrect because it doesn't refer to a specific commit and the dates are not always sequential. It would be even more wrong if it was the build date, as that doesn't refer to anything to do with the version. -- [[User:thestinger|thestinger]] 21:33, 23 January 2015 (UTC)<br />
<br />
::''it doesn't refer to a specific commit''<br />
::<br />
::Neither does "r1581.2b039da" refer to a specific commit without the .git repo cmdline interaction, and it is considered best practice to prune $pkgdir of .git:<br />
::<br />
find "$pkgdir" -type d -name .git -exec rm -r '{}' +<br />
::<br />
::Can you explain what you mean by "the dates are not always sequential"? The Date standard looks like this:<br />
::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::<br />
::It displays the latest commit date from the upstream Git repo.<br />
::<br />
::In the edge case of breaking changes occurring upstream in Git repos on the same day, then package maintainers should increment pkgrel. In practice, "2014-01-01" is much more readable and useful than "r1581.2b039da". The readability benefits of "2014-01-01" vs. "r1581.2b039da" should not be underestimated due to edge cases. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 18:39, 24 January 2015 (UTC)<br />
:::A git commit id certainly refers to a specific commit. I don't know why you think this has anything to do with shipping the VCS repository in the package. The commit date of the most recent commit may be from 20 weeks ago while the earlier commits were from last week. Git does not have a linear history. It's not going to be changed to use a version format where it can go both backwards and forwards with no way of tracing it back to the commit. Readability is worthless if the information isn't meaningful... There are 2 hard requirements: newer revisions must have higher package versions without exceptions, and it must be possible to trace it back to a commit to properly identify and report bugs. -- [[User:thestinger|thestinger]] 18:53, 24 January 2015<br />
:::<br />
::::<br />
::::I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.<br />
::::<br />
::::Can you show me where to find "r1581.2b039da" on a GitHub/BitBucket repo? It doesn't exist anywhere that I can see. You need to have the repo locally, then cd into the Git repo and run:<br />
::::<br />
git rev-list --count HEAD<br />
::::<br />
::::That is work-intensive, and it conflicts with the best practice of pruning AUR packages of .git repos.<br />
::::<br />
::::I previously used the Wiki-recommended Numeric standard, so it's not like I haven't used it. I switched to the Date standard, updating hundreds of packages to reflect it. Why do you suppose that is?<br />
::::<br />
:::: ''Readability is worthless if the information isn't meaningful''<br />
::::You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581". I say this after maintaining for years, hundreds of Git packages in the AUR. You can tell by grepping `pacman -Q` exactly which AUR git packages are out of date with a two-second visit to GitHub. The Date standard is incredibly actionable and pragmatic not to mention simple and immediately understandable by anyone.<br />
::::<br />
:::: ''newer revisions must have higher package versions without exceptions''<br />
::::<br />
::::Not a problem: "2014-01-01" < "2014-01-02"<br />
::::<br />
:::: ''it must be possible to trace it back to a commit to properly identify and report bugs''<br />
::::<br />
:::: Given how frequently "stable" Go packages and C packages pull in Git dependencies as part of their build process without specifying a certain commit, I disagree with this proposition. Why would recording the version of acmedaemon as 1.5, when it pulls in Git packages without specifying commit ID, be all that different in bug reports than "2014-01-01"? In both cases, you will not be able to track down the exact cause of the bug by commit. In both cases, you will in all likelihood end up consulting the build date. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 03:32, 25 January 2015 (UTC)<br />
<br />
:::::''I am quite certain of what a commit ID looks like, e.g. 2d5749d0315a59f4a8bf73ebbe757b227c8c17a3, not r1581.2b039da.''<br />
:::::In your scenerio, 2b039da is the short version of the commit hash and does point to a specific commit. As for where you find it on Github, it's listed on the commit log, of course. Just look at the right hand side of the page.<br />
:::::''You'd be hard pressed to convince me that the date "2014-01-01" is somehow *less* semantically meaningful or actionable than "r1581".''<br />
:::::In this case, human readability really is meaningless. Machine readability is all that matters.<br />
:::::''Not a problem: "2014-01-01" < "2014-01-02"''<br />
:::::And what happens when the commit after that is dated 2013-12-31? As thestinger pointed out, Git is not linear.<br />
:::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 03:40, 25 January 2015 (UTC)<br />
<br />
::::::''2b039da is the short version of the commit hash''<br />
::::::<br />
::::::Can this information be easily compared on GitHub to your local package version to check if it is out of date? The answer is no.<br />
::::::<br />
::::::It is not actionable, except by cloning the repo yourself, running the Git command, and then manually scanning the Git log for short versions. It's very work-intensive.<br />
::::::<br />
::::::''Git is not linear''<br />
::::::<br />
::::::Neither are stable packages on PyPi: https://pypi.python.org/pypi/tackpy/0.9.9a<br />
::::::<br />
::::::Pacman views the upgrade of 0.9.9 -> 0.9.9a as a downgrade. See https://aur.archlinux.org/packages/python2-tackpy for a real world example of this edge case. Edge cases should be no reason to prevent readers of the wiki to make informed choices about Git packaging standards. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:08, 25 January 2015 (UTC)<br />
<br />
:::::::Yes, the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page.<br />
:::::::As for PyPi's versioning scheme, their choice is different than what Arch's vercmp assumes. The packager needs to take this into account, just as all packagers must take upstream's idiosyncrasies into account. I don't see how it's relevant here.<br />
:::::::You also never answered my question, what happens when the last commit is dated before the commit previous to it? This question is critical, as it would cause your versioning scheme to go backwards by any and all measures. That makes it unacceptable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:15, 25 January 2015 (UTC)<br />
<br />
::::::::Incorrect.<br />
::::::::<br />
printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)<br />
::::::::<br />
::::::::The output of the above command does not correspond to any piece of information on GitHub.<br />
::::::::<br />
::::::::If PyPi packagers should take edge cases into account for PyPi packages, then they should do the same for Git packages. Edge cases aren't reason enough to scrub a competing standard from the wiki. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:23, 25 January 2015 (UTC)<br />
<br />
:::::::::I'm sorry if you can't find this information on GitHub. It's very, very plainly displayed in the places I already pointed you to. If you would take a minute to check instead of just jumping at me, you might find it.<br />
:::::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 04:31, 25 January 2015 (UTC)<br />
<br />
::::::::::''the short hash of each commit is listed in the commit log. Also note that the revision count (the "r" number listed first) is also listed at the top of each repo's page''.<br />
::::::::::<br />
::::::::::This is (partially) incorrect. The short hash of each commit is not listed. What is listed in the commit log is the truncated commit ID.<br />
::::::::::<br />
::::::::::The revision count point I will retract. It didn't appear to work for my own Git repos, but that was because I ran the command from a Git subrepo (edge case :). The date still has the advantage of being more human readable than r1582. If a package has version 2011-10-22, I will know this project is either unmaintained, or it's been a really long time since I last rebuilt it. All without leaving the terminal. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:33, 25 January 2015 (UTC)<br />
<br />
::::::::::It's also very easy to look up or link to commits via the abbreviated commit hashes or proper identifiers produced by {{ic|git describe}}. -- [[User:thestinger|thestinger]] 04:33, 25 January 2015 (UTC)<br />
<br />
::::::That has nothing to do with non-linear history. It has to do with an incompatibility between Pacman's version comparison and the one chosen by the project. There are ways of dealing with that, but it has nothing to do with this discussion. -- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
:::::The ideal version is the one produced by {{ic|git describe}}, because it's easily understood by humans (last tag, commits since last tag, abbreviated commit), is also understood by the various Git commands and GitHub and is monotonically increasing thanks to the inclusion of the last version and revision count since then. The versions it produces ({{ic|10-7-g8537989}}) can be directly used with commands like {{ic|git show}}. Unlike the build date, it identifies a unique revision of the project, including the state of any submodules.<br />
<br />
:::::The only case where another method should be used is when the project doesn't yet have any tagged release or does the releases in a way that's not very sane. The releases ''should'' be tagged on master with additional tags in stable branches for fixes backported to old releases. If this isn't the case, the {{ic|git describe}} output needs to be emulated. A date is a poor way of doing that, because it's not connected to a specific point in the revision history.<br />
<br />
:::::The only case where the commit date would work is if Git is being used as a crippled centralized version control system. If all commits get created against master (no merging branches or patches) in a centralized repository where the system clock is never moved backwards, it could work... but that's not the reality of non-linear, distributed version control.<br />
<br />
:::::A build date is even worse, because it only refers to the local state of time and the local state of the repository. Commits from before that timestamp will often be pushed to the repository.<br />
<br />
:::::-- [[User:thestinger|thestinger]] 04:24, 25 January 2015 (UTC)<br />
<br />
::::::A packaging standard must be compatible with the lowest common denominator. A minority of Git repos are properly tagged. The Date works as a standard, tags do not.<br />
::::::<br />
git log -1 --format="%cd" --date=short | sed "s|-||g"<br />
::::::<br />
::::::The output of the above command shows the date of the most recent commit. If the most recent commit date happens to come before the date of a previous commit, I do understand this is suboptimal, but I consider it an edge case. Even in big projects with contributors in different time zones you will typically see branches merged in with PRs. PRs reset the date to something recent. The linearity of Git is rarely problematic, but I do see where you're coming from (I'm also a happy user of archversion for keeping packages up to date, though archversion works with the Date standard too :) --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 04:59, 25 January 2015 (UTC)<br />
<br />
:::::::The {{ic|git describe}} versioning system is the standard defined and used by Git itself. The dashes need to be converted into dots for {{ic|pkgver}} and an {{ic|r}} ''may'' be inserted to make it clearer which part is the revision number. If version-based tags on master are available, this is the only sane way to do it.<br />
<br />
:::::::Git defaults to fast-forwarding / applying patches without merge commits, as long as there are no conflicts. GitHub will ''always'' generate a merge commit but that's not true for anything applied / merged by the developers and then pushed to master. -- [[User:thestinger|thestinger]] 05:24, 25 January 2015 (UTC)<br />
<br />
:::::::You've made the claim that most git repos aren't properly tagged, not only now but to me previously. Do you have anything to back that up? IME, the large majority of projects that are in a usable state are either tagged or get tagged as they become stable.<br />
:::::::[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 05:27, 25 January 2015 (UTC)<br />
<br />
::::::::OK:<br />
::::::::<br />
git init<br />
::::::::<br />
::::::::You now have your very own untagged Git repo :).<br />
::::::::<br />
::::::::The majority of Git repos are untagged. If you want to have a standard compatible with the lowest common denominator, by definition you cannot depend on tags being there.<br />
::::::::<br />
::::::::I regularly package Git software in the alpha stages and software maintained by people who are unfamiliar with tagging or aren't bothered to tag. --[[User:Atweiden|Atweiden]] ([[User talk:Atweiden|talk]]) 07:15, 25 January 2015 (UTC)<br />
<br />
::::As suggested in [[VCS package guidelines#Fallback]], I think the only date that can be used is the build date: for example I've recently used it in [https://aur.archlinux.org/packages/te/textadept-common-git/PKGBUILD a PKGBUILD] for a repo without tags or branches, also appending the first 7 characters of the commit hash (the repo is not cloned, so I could only use ''git-ls-remote''). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:30, 25 January 2015 (UTC)<br />
<br />
== Updating a CVS repo ==<br />
<br />
I don't use cvs. How can you describe the pkgver for cvs (for pacman 4.1)? <br><br />
-- [[User:Dracorp|Dracorp]] ([[User talk:Dracorp|talk]]) 09:31, 6 April 2013 (UTC)<br />
<br />
:CVS is not supported in pacman 4.1 like the other VCS tools. You will need to update pkgver manually until CVS support is added.<br />
:-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 22:44, 15 April 2013 (UTC)<br />
<br />
::Yeah, but how about mentioning that in the article (as well as giving a download example)? Even if it's not that common anymore.<br />
::--[[User:Det|Det]] ([[User talk:Det|talk]]) 22:39, 2 May 2013 (UTC)<br />
<br />
:::The download example can still be found in {{ic|/usr/share/pacman/}}. The next version of the ABS package should update it a bit so the download happens in the prepare function where it belongs. As for pkgver, I think the generic example using date covers that, as there's not a way to get a version number from a CVS repo. Maybe a note to that effect?<br />
::: -- [[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 07:17, 15 May 2013 (UTC)<br />
<br />
::::That makes the most sense, but it might also be a good idea to rename the [[VCS PKGBUILD Guidelines#Fallback|"Fallback"]] section to something like "Fallback / CVS" to make it more obvious even when you're just checking out the table of contents.<br />
<br />
::::But as for ABS, as far as I can tell the last commit was over [https://projects.archlinux.org/abs.git/log/ 8 months] ago.<br />
::::--[[User:Det|Det]] ([[User talk:Det|talk]]) 05:54, 19 May 2013 (UTC)<br />
<br />
:::::Hmm, there were a number of patches submitted last month for cleaning up the prototypes, looks like none have been committed yet. I do remember a discussion (IRC maybe?) questioning the proper place for the prototypes, so maybe that's why? Looking at the patches, I was mistaken anyway; they didn't update the darcs or cvs prototypes. Simple enough, I'll send in a patch myself.<br />
:::::--[[User:Scimmia|Scimmia]] ([[User talk:Scimmia|talk]]) 08:22, 19 May 2013 (UTC)<br />
<br />
: I use this dirty hack: {{ic|<nowiki>cvs history -c -a | cut -d' ' -f2 | sort -u | tail -n 1 | sed 's|-||g"</nowiki>}} ; could probably be improved.<br />
:--[[User:Buhman|Buhman]] ([[User talk:Buhman|talk]]) 18:00, 6 June 2013 (UTC)<br />
<br />
<br />
== pkgver function for hg based on tags ==<br />
<br />
I recent came across a way with hg to show the most recent tag, as well as the number of commits from this tag (similar to the output of {{ic|git describe}}.) <br />
<br />
{{hc|<nowiki>pkgver() {<br />
cd local_repo<br />
hg log -r . --template '{latesttag}.{latesttagdistance}.{node|short}\n'<br />
}</nowiki>|<br />
3.0.1.40.ee9a2543fcd6<br />
}}<br />
<br />
Please could this be included in the page.<br />
<br />
[[User:Garyvdm|Garyvdm]] ([[User talk:Garyvdm|talk]]) 09:03, 23 July 2013 (UTC)<br />
<br />
== shorten hg version ==<br />
<br />
To prevent long package file name,<br />
It is proper to use this format<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd $_repo<br />
_id=$(hg identify -i)<br />
echo $(hg identify -n).${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:30, 26 August 2013 (UTC)<br />
<br />
== fossil ==<br />
<br />
{{bc|<nowiki>pkgver() {<br />
cd local_repo<br />
_id=$(cat manifest.uuid 2>/dev/null)<br />
echo ${_id:0:4}<br />
}</nowiki><br />
}}<br />
--[[User:Dlin|Dlin]] ([[User talk:Dlin|talk]]) 05:36, 26 August 2013 (UTC)<br />
<br />
== Locking ==<br />
<br />
Re [https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=364087&oldid=364032], I hope I wasn't the straw that broke the camel's back. I still fail to see why the Git section should be that large though, also in comparison to the other sections. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:26, 6 March 2015 (UTC)<br />
<br />
== set -o pipefail ==<br />
<br />
[https://wiki.archlinux.org/index.php?title=VCS_package_guidelines&diff=prev&oldid=363918 This change] mentioned {{ic|set -o ...}} as one of the reasons for reverting, nevertheless one example using {{ic|set -o pipefail}} still remains: [[VCS_package_guidelines#Git]] (the last example in that section). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:41, 6 March 2015 (UTC)<br />
<br />
== Guidelines on updating version numbers ==<br />
<br />
There are a few version control AUR packages out there which use the correct combined format of release and git commit. However, sometimes the maintainers refuse to update the default pkgver upon new releases of the software, stating that it's unnecessary since it's updated automatically during installation anyway. While this is true, I personally feel it should still be the maintainer's responsibility to update the default pkgver upon actual releases (not individual commits) as otherwise a user will never receive an automatic update and instead has to force-reinstall all(!) such packages regularly.<br />
<br />
Should we add this to the guidelines or how do others feel about this?</div>Airbladerhttps://wiki.archlinux.org/index.php?title=Unclutter&diff=381848Unclutter2015-07-12T07:37:30Z<p>Airblader: Added unclutter-xfixes as an alternative because unclutter is old, hacky and broken</p>
<hr />
<div>[[Category:X Server]]<br />
Unclutter hides your X mouse cursor when you do not need it, to prevent it from getting in the way. You have only to move the mouse to restore the mouse cursor. Unclutter is very useful in tiling window managers where you do not need the mouse often.<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] {{Pkg|unclutter}} from the [[official repositories]] or the modern rewrite {{AUR|unclutter-xfixes-git}} from the [[AUR]].<br />
<br />
== Usage ==<br />
<br />
Use your ''.xinitrc'' file or WM/DE to start unclutter. For example, add the following to your ''.xinitrc'':<br />
<br />
unclutter &<br />
<br />
== Known bugs ==<br />
<br />
=== Misbehaviour of the mouse cursor ===<br />
<br />
If you experience issues when using unclutter in conjunction with a tiling window manager (such as [[xmonad]] or [[i3]]), install {{AUR|unclutter-xfixes-git}} instead or use the {{ic|-grab}} option:<br />
<br />
unclutter -grab &<br />
<br />
{{Note|The {{ic|-grab}} option breaks some screen locking applications such as ''slock'' and ''i3lock''.}}<br />
<br />
Unclutter could cause unusual mouse behaviour in some SDL Games. The mouse cursor might be reset to some positions in the screen because of<br />
this problem. The details can be found [https://bugs.launchpad.net/ubuntu/+source/unclutter/+bug/61105 here].<br />
<br />
There are two known workarounds for this. You can either add {{ic|SDL_VIDEO_X11_DGAMOUSE&#61;0}} to your environment variables which does not work for all games or run unclutter with<br />
{{ic|-grab}} option. However, it is important to note that the grab option may cause some applications such as gksu to not work properly.<br />
<br />
== Alternatives ==<br />
<br />
=== unclutter-xfixes ===<br />
<br />
Unclutter is a tool from the early 90s and has not been updated since. It works by creating fake windows or active pointer grabs, both of which often cause problems. By now, the X11 extensions Xinput2 and Xfixes have been released and are commonly found on most user systems. Using those, {{AUR|unclutter-xfixes-git}} can provide the cursor hiding functionality without interfering with any application.<br />
<br />
== See also ==<br />
<br />
http://linuxappfinder.com/package/unclutter - Unclutter on Linux App Finder</div>Airblader