https://wiki.archlinux.org/api.php?action=feedcontributions&user=Thiagowfx&feedformat=atomArchWiki - User contributions [en]2024-03-29T09:50:20ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Rust_packaging_guidelines&diff=711328Rust packaging guidelines2022-01-19T02:29:57Z<p>Thiagowfx: create redirect</p>
<hr />
<div>#REDIRECT [[Rust package guidelines]]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Overlay&diff=711230Overlay2022-01-18T18:39:18Z<p>Thiagowfx: create redirect</p>
<hr />
<div>#REDIRECT [[Overlay filesystem]]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Tailscale&diff=710575Tailscale2022-01-16T22:37:26Z<p>Thiagowfx: add related articles: wireguard</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
{{Related articles start}}<br />
{{Related|Wireguard}}<br />
{{Related articles end}}<br />
Tailscale builds on top of [[WireGuard]] and provides OAuth2 (SSO), OpenID, and SAML authentication for peers to build a mesh network. It is crossplatform, has ACL settings and internal DNS.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|tailscale}}. Alternatively, one can use unstable builds by installing the {{AUR|tailscale-git}} or {{AUR|tailscale-unstable-bin}} package.<br />
<br />
== Usage ==<br />
<br />
To use ''tailscale'', [[enable/start]] {{ic|tailscaled.service}} and run the server as follows:<br />
<br />
# tailscale up<br />
<br />
You can authenticate a headless machine by specifying [https://login.tailscale.com/admin/settings/keys auth key] {{ic|tailscale up --authkey&#61;tskey-KEY}}.<br />
<br />
== See also ==<br />
<br />
* https://tailscale.com/</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Tailscale&diff=710574Tailscale2022-01-16T22:36:08Z<p>Thiagowfx: /* Usage */ grammar</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
Tailscale builds on top of [[WireGuard]] and provides OAuth2 (SSO), OpenID, and SAML authentication for peers to build a mesh network. It is crossplatform, has ACL settings and internal DNS.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|tailscale}}. Alternatively, one can use unstable builds by installing the {{AUR|tailscale-git}} or {{AUR|tailscale-unstable-bin}} package.<br />
<br />
== Usage ==<br />
<br />
To use ''tailscale'', [[enable/start]] {{ic|tailscaled.service}} and run the server as follows:<br />
<br />
# tailscale up<br />
<br />
You can authenticate a headless machine by specifying [https://login.tailscale.com/admin/settings/keys auth key] {{ic|tailscale up --authkey&#61;tskey-KEY}}.<br />
<br />
== See also ==<br />
<br />
* https://tailscale.com/</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=HiDPI&diff=708415HiDPI2022-01-01T18:57:13Z<p>Thiagowfx: /* Elementary (EFL) */ remove extra whitespace</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:HiDPI]]<br />
[[zh-hans:HiDPI]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related articles end}}<br />
HiDPI (High Dots Per Inch) displays, also known by Apple's "[[wikipedia:Retina Display|Retina Display]]" marketing name, are screens with a high resolution in a relatively small format. They are mostly found in high-end laptops and monitors.<br />
<br />
Not all software behaves well in high-resolution mode yet. Here are listed most common tweaks which make work on a HiDPI screen more pleasant.<br />
<br />
== Desktop environments ==<br />
<br />
=== GNOME ===<br />
<br />
To enable HiDPI, navigate to ''Settings > Devices > Displays > Scale'' and choose an appropriate value. Or, use gsettings:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "[{'Gdk/WindowScalingFactor', <2>}]"<br />
$ gsettings set org.gnome.desktop.interface scaling-factor 2<br />
<br />
{{Note|1=GNOME only allows integer scaling numbers to be set. 1 = 100%, 2 = 200%, etc. See [[#Fractional scaling]] below.}}<br />
<br />
==== Fractional scaling ====<br />
<br />
A setting of {{ic|2, 3, etc}}, which is all you can do with {{ic|scaling-factor}}, may not be ideal for certain HiDPI displays and smaller screens (e.g. small tablets). Fractional scaling is possible on both Wayland and Xorg, though the process differs.<br />
<br />
===== Wayland =====<br />
<br />
Enable the experimental fractional scaling feature:<br />
<br />
$ gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"<br />
<br />
then open ''Settings > Devices > Displays'' (the new options may only appear after a restart).<br />
<br />
{{Note|Enabling fractional scaling can result in blur for legacy applications using XWayland, ''even if only integer scales are used'', because the rendering method changes.}}<br />
<br />
To enable the option for all users, create the following three files with the corresponding content<br />
<br />
{{hc|/etc/dconf/profile/user|<nowiki><br />
user-db:user<br />
system-db:local<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/local.d/00-hidpi|<nowiki><br />
[org/gnome/mutter]<br />
experimental-features=['scale-monitor-framebuffer']<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/locks/hidpi|<nowiki><br />
/org/gnome/mutter/experimental-features<br />
</nowiki>}}<br />
<br />
Then run {{ic|dconf update}} and restart the machine. This will permanently lock the option.<br />
<br />
===== Xorg =====<br />
<br />
You can achieve any non-integer scale factor by using a combination of GNOME's {{ic|scaling-factor}} and [[xrandr]]. This combination keeps the TTF fonts properly scaled so that they do not become blurry if using {{ic|xrandr}} alone. You specify zoom-in factor with {{ic|gsettings}} and zoom-out factor with [[xrandr]].<br />
<br />
First scale GNOME up to the minimum size which is too big. Usually "2" is already too big, otherwise try "3" etc. Then start scaling down by setting zoom-out factor with [[xrandr]]. First get the relevant output name, the examples below use {{ic|eDP1}}. Start e.g. with zoom-out 1.25 times. If the UI is still too big, increase the scale factor; if it is too small decrease the scale factor.<br />
<br />
$ xrandr --output eDP1 --scale 1.25x1.25<br />
<br />
{{Note|To allow the mouse to reach the whole screen, you may need to use the {{ic|--panning}} option as explained in [[#Side display]].}}<br />
<br />
To ensure that the settings persist across reboots, you may choose to use {{Pkg|autorandr}}. Refer to [https://askubuntu.com/a/1130337 this StackOverflow] for more information.<br />
<br />
{{Accuracy|The following was initially added under [[#X Resources]]. Clarify how it integrates with the info there or that above for GNOME.|section=GNOME ignores X settings}}<br />
<br />
GNOME ignores X settings due to its xsettings Plugin in Gnome Settings Daemon, where DPI setting is hard coded.<br />
There is blog entry for [http://blog.drtebi.com/2012/12/changing-dpi-setting-on-gnome-34.html recompiling Gnome Settings Daemon].<br />
In the source documentation there is another way mentioned to set X settings DPI:<br />
<br />
You can use the gsettings, just make sure to read previous setting first and merge it. In just simply set it with this command:<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Xft/DPI': <153600>}"<br />
<br />
From README.xsettings<br />
<br />
Noting that variants must be specified in the usual way (wrapped in <>).<br />
<br />
Note also that DPI in the above example is expressed in 1024ths of an inch.<br />
<br />
==== Text Scaling ====<br />
<br />
Alternatively, or in addition to changing the display scaling, you can separately scale text. This can be done by navigating to ''Fonts > Scaling Factor'' in Gnome Tweaks, or using gsettings. Note that the text scaling factor need not be limited to whole integers, for example:<br />
<br />
$ gsettings set org.gnome.desktop.interface text-scaling-factor 1.5<br />
<br />
===== GTK+ vs Gnome Shell elements on Xorg =====<br />
<br />
Adjusting the text scaling as per the above only affects GTK+ elements of the GNOME desktop. This should cover everything on Wayland. However, those on an Xorg session may find that they need to make further adjustments on HiDPI environments, since the GNOME Shell UI (including the top bar, dock, application menus, etc.) relies separately on the [https://developer.gnome.org/st/stable/ St]{{Dead link|2021|11|11|status=404}} toolkit. Note that this is a long-standing issue to which a [https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/486 patch] has been merged and available for Gnome Shell 3.35 onward. For older releases, Xorg users can resolve most of the Gnome shell scaling problems by manually editing the shell theme that they are currently using. The relevant CSS files are normally located at {{ic|/usr/share/themes/YOUR-THEME/gnome-shell/gnome-shell.css}}. Users should increase all "font-size" elements in this file in proportion to their display scaling (doubling font sizes for 200% scaling, etc.) For example, the top of an edited CSS file for the [https://github.com/adapta-project/adapta-gtk-theme Adapta] shell theme might look like:<br />
<br />
{{hc|usr/share/themes/Adapta/gnome-shell/gnome-shell.css|2=<br />
stage { font-size: 20pt; font-family: Roboto, Noto Sans, Sans-Serif; color: #263238; }<br />
}}<br />
<br />
Once these changes have been saved, activate them by switching to another theme (for example, using {{pkg|gnome-tweaks}}) and then reverting back again. The top bar, application menus, calendar, and other shell elements should now be correctly scaled.<br />
<br />
In addition to editing the relevant shell theme's CSS file, users on Xorg may also wish to increase the title bar font at the top of open applications. This can be done through the dconf editor ({{ic|org > gnome > desktop > wm > preferences :: titlebar-font}}). Note that the {{ic|title-bar-uses-system-fonts}} option should also be turned off. Alternatively, use gsettings:<br />
<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-font 'Cantarell Bold 22' ## Change as needed<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-uses-system-font false<br />
<br />
=== KDE Plasma ===<br />
<br />
You can use Plasma's settings to fine tune font, icon, and widget scaling. This solution affects both Qt and GTK applications.<br />
<br />
To adjust font, widget, and icon scaling together:<br />
<br />
# ''System Settings > Display and Monitor > Display Configuration > Global Scale''<br />
# Drag the slider to the desired size<br />
# Restart for the settings to take effect<br />
<br />
To adjust only font scaling:<br />
<br />
# ''System Settings > Fonts''<br />
# Check "Force fonts DPI" and adjust the DPI level to the desired value. This setting should take effect immediately for newly started applications. You will have to logout and login for it to take effect on Plasma desktop.<br />
<br />
To adjust only icon scaling:<br />
<br />
# ''System Settings > Icons > Advanced''<br />
# Choose the desired icon size for each category listed. This should take effect immediately.<br />
<br />
==== Tray icons with fixed size ====<br />
<br />
The tray icons are not scaled with the rest of the desktop, since Plasma ignores the Qt scaling settings by default. To make Plasma respect the Qt settings, [[Environment variables|set]] {{ic|1=PLASMA_USE_QT_SCALING=1}}.<br />
<br />
=== Xfce ===<br />
<br />
Xfce supports HiDPI scaling which can be enabled using the settings manager:<br />
<br />
# Go to ''Settings Manager > Appearance > Settings > Window Scaling'' and select 2 as the scaling factor.<br />
# Go to ''Settings Manager > Window Manager > Style'' and select {{ic|Default-xhdpi}} theme.<br />
<br />
Alternatively, it is possible to do the same from command line using {{ic|xfconf-query}}:<br />
<br />
xfconf-query -c xsettings -p /Gdk/WindowScalingFactor -s 2<br />
xfconf-query -c xfwm4 -p /general/theme -s Default-xhdpi<br />
<br />
After either of the above changes, fonts in some GTK applications may still not be scaled; you may additionally do the following (see [[#GDK 3 (GTK 3)]]):<br />
<br />
# Go to ''Settings Manager > Appearance > Fonts > Custom DPI setting'' and change from 96 to 192<br />
# Set the environment variable {{ic|1=GDK_DPI_SCALE=0.5}} (e.g. in {{ic|~/.profile}}) to un-scale some fonts that would be scaled twice<br />
<br />
The steps above would set 2x scaled resolution for Xfce and other GTK 3 apps.<br />
<br />
Scaling for Qt 5 apps should be set manually, see [[#Qt 5]]. Note that if you set a Custom DPI for fonts above, you likely need to set {{ic|1=QT_FONT_DPI=96}} to avoid double-scaling of fonts in Qt applications.<br />
<br />
=== Cinnamon ===<br />
<br />
Has good support out of the box.<br />
<br />
=== Enlightenment ===<br />
<br />
For E18, go to the E Setting panel. In ''Look > Scaling'', you can control the UI scaling ratios. A ratio of 1.2 seems to work well for the native resolution of the MBPr 15" screen.<br />
<br />
== X Resources ==<br />
<br />
If you are not using a desktop environment such as KDE, Xfce, or other that manipulates the X settings for you, you can set the desired DPI setting manually via the {{ic|Xft.dpi}} variable in [[Xresources]]:<br />
<br />
{{hc|~/.Xresources|2=<br />
Xft.dpi: 192<br />
<br />
! These might also be useful depending on your monitor and personal preference:<br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintfull<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
}}<br />
<br />
For {{ic|Xft.dpi}}, using integer multiples of 96 usually works best, e.g. 192 for 200% scaling.<br />
<br />
Make sure the settings are loaded properly when X starts, for instance in your {{ic|~/.xinitrc}} with {{ic|xrdb -merge ~/.Xresources}} (see [[Xresources]] for more information).<br />
<br />
This will make the font render properly in most toolkits and applications, it will however not affect things such as icon size!<br />
Setting {{ic|Xft.dpi}} at the same time as toolkit scale (e.g. {{ic|GDK_SCALE}}) may cause interface elements to be much larger than intended in some programs like firefox.<br />
<br />
== X Server ==<br />
<br />
{{Accuracy|{{Pkg|libxft}} is a ''font rendering interface library'', the {{ic|Xft.dpi}} setting was not intended to be abused by other applications. On the other hand, the {{ic|xorg.conf}} value should affect everything.}}<br />
<br />
Some programs may still interpret the DPI given by the X server (most interpret X Resources, though, directly or indirectly). Older versions of i3 (before 2017) and Chromium (before 2017) used to do this.<br />
<br />
To verify that the X Server has properly detected the physical dimensions of your monitor, use the ''xdpyinfo'' utility from the {{Pkg|xorg-xdpyinfo}} package:<br />
<br />
{{hc|$ xdpyinfo {{!}} grep -B 2 resolution|<br />
screen #0:<br />
dimensions: 3200x1800 pixels (423x238 millimeters)<br />
resolution: 192x192 dots per inch<br />
}}<br />
<br />
This example uses inaccurate dimensions (423mm x 328mm, even though the Dell XPS 9530 has 346mm x 194mm) to have a clean multiple of 96 dpi, in this case 192 dpi. This tends to work better than using the correct DPI — Pango renders fonts crisper in i3 for example.<br />
<br />
If the DPI displayed by xdpyinfo is not correct, see [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
== GUI toolkits ==<br />
<br />
=== Qt 5 ===<br />
<br />
Since Qt 5.6, Qt 5 applications can be instructed to honor screen DPI by setting the {{ic|QT_AUTO_SCREEN_SCALE_FACTOR}} environment variable:<br />
<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=1<br />
<br />
If automatic detection of DPI does not produce the desired effect, scaling can be set manually per-screen ({{ic|QT_SCREEN_SCALE_FACTORS}}) or globally ({{ic|QT_SCALE_FACTOR}}). For more details see the [https://blog.qt.io/blog/2016/01/26/high-dpi-support-in-qt-5-6/ Qt blog post] or [https://doc.qt.io/qt-5/highdpi.html Qt developer documentation].<br />
<br />
{{Note|<br />
* If you manually set the screen factor, it is important to set {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} otherwise some applications which explicitly force high DPI enabling get scaled twice.<br />
* {{ic|QT_SCALE_FACTOR}} scales fonts, but {{ic|QT_SCREEN_SCALE_FACTORS}} does not scale fonts.<br />
* If you also set the font DPI manually in ''xrdb'' to support other toolkits, {{ic|QT_SCALE_FACTORS}} will give you huge fonts.<br />
* If you have multiple screens of differing DPI ie: [[#Side display]] you may need to do {{ic|1=QT_SCREEN_SCALE_FACTORS="2;2"}}<br />
}}<br />
<br />
An [https://bugreports.qt.io/browse/QTBUG-53022 alternative] is e.g.:<br />
<br />
QT_FONT_DPI=96 clementine<br />
<br />
=== GDK 3 (GTK 3) ===<br />
<br />
{{Note|As stated in the [[#X Resources]] section, if you have xft.dpi set to a larger dpi, it will make other scales larger than usual, including GDK.}} <br />
<br />
Setting the GDK scale will scale the UI, however it will not scale icons. If you are using a minimal window manager where you are setting the dpi via Xft.dpi, GDK should scale perfectly fine with it. In other cases, [https://developer.gnome.org/gtk3/stable/gtk-x11.html do the following]:<br />
<br />
To scale UI elements by an integer factor:<br />
<br />
$ export GDK_SCALE=2<br />
<br />
To undo scaling of text, fractional scale can be used:<br />
<br />
$ export GDK_DPI_SCALE=0.5<br />
<br />
=== GTK 2 ===<br />
<br />
Scaling of UI elements is not supported by the toolkit itself, however it's possible to generate a theme with elements pre-scaled for HiDPI display using {{AUR|themix-full-git}}.<br />
<br />
=== Electron ===<br />
<br />
[https://electronjs.org/ Electron] applications (e.g. {{AUR|slack-desktop}}, {{pkg|signal-desktop}}, etc.) can be configured to use a custom scaling value by adding a {{ic|1=--force-device-scale-factor}} flag to the .desktop file. This is normally located at {{ic|/usr/share/applications/}}, and can normally be overridden on a per-user basis by copying it to {{ic|~/.local/share/applications}}. The flag should be added to the line beginning with "Exec=". For example:<br />
<br />
{{hc|/usr/share/applications/slack.desktop|2=<br />
Exec=env LD_PRELOAD=/usr/lib/libcurl.so.3 /usr/bin/slack --force-device-scale-factor=1.5 %U<br />
}}<br />
<br />
=== Elementary (EFL) ===<br />
<br />
To scale UI elements by a factor of 1.5:<br />
<br />
export ELM_SCALE=1.5<br />
<br />
For more details see https://phab.enlightenment.org/w/elementary/<br />
<br />
=== GNUstep ===<br />
<br />
GNUstep applications that use its gui (AppKit) library accept a {{ic|GSScaleFactor}} property in their defaults (STEP preferences). To define a scaling factor of 1.5 for all apps:<br />
<br />
defaults write NSGlobalDomain GSScaleFactor 1.5<br />
<br />
Some automatic detection was possible back in 2011, but the code responsible for the X11 backend was [https://github.com/gnustep/libs-back/commit/337ce46bba304732d9a7c7495a3dd245a3219660 commented out] thereafter.<br />
<br />
== Boot managers ==<br />
<br />
=== GRUB ===<br />
<br />
==== Lower the framebuffer resolution ====<br />
<br />
Set a lower resolution for the framebuffer as explained in [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
==== Change GRUB font size ====<br />
<br />
Find a ttf font that you like in {{ic|/usr/share/fonts/}}.<br />
<br />
Convert the font to a format that GRUB can utilize:<br />
<br />
# grub-mkfont -s 30 -o /boot/grubfont.pf2 /usr/share/fonts/FontFamily/FontName.ttf<br />
<br />
{{Note|Change the {{ic|-s 30}} parameter to modify the font size}}<br />
<br />
Edit {{ic|/etc/default/grub}} to set the new font as shown in [[GRUB/Tips and tricks#Background image and bitmap fonts]]:<br />
<br />
GRUB_FONT="/boot/grubfont.pf2"<br />
<br />
{{Note|{{ic|GRUB_THEME}} overrides {{ic|GRUB_FONT}} if it is used.}}<br />
<br />
Finally [[GRUB#Generate the main configuration file|regenerate the main configuration file]].<br />
<br />
{{Tip|The font size can also be changed with the GUI tool {{Pkg|grub-customizer}}.}}<br />
<br />
=== systemd-boot ===<br />
<br />
Adding the following line and running {{ic|bootctl update}} increases font-size in the [[systemd-boot#Loader_configuration|systemd-boot]] menu:<br />
<br />
{{hc|/boot/loader/loader.conf|2=<br />
console-mode 1<br />
}}<br />
<br />
== Applications ==<br />
<br />
If you are running a Wayland session, but application is running via Xwayland (either because it does not support Wayland natively or because it uses X11 by default), you could still get blurry fonts and interface, even if the application supports HiDPI. See [https://bugs.kde.org/show_bug.cgi?id=389191 this bug report]. See also [[Wayland#Detect Xwayland applications visually]].<br />
<br />
=== Atom ===<br />
<br />
Add {{ic|1=--force-device-scale-factor=2}} as a flag to the atom.desktop file:<br />
<br />
{{hc|/usr/share/applications/atom.desktop|2=<br />
Exec=/usr/bin/atom --force-device-scale-factor=2 %F<br />
}}<br />
<br />
=== Browsers ===<br />
<br />
==== Firefox ====<br />
<br />
Firefox should use the [[#GDK 3 (GTK 3)]] settings. However, the suggested {{ic|GDK_SCALE}} suggestion does not consistently scale the entirety of Firefox, and does not work for fractional values (e.g., a factor of 158DPI/96DPI = 1.65 for a 1080p 14" laptop). You may want to use {{ic|GDK_DPI_SCALE}} instead. Another option, which will avoid Firefox-specific settings in many setups is to use the settings in [[#X Resources]] as Firefox should respect the {{ic|Xft.dpi}} value defined there.<br />
<br />
To override those, open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|layout.css.devPixelsPerPx}} to {{ic|2}} (or find the one that suits you better; {{ic|2}} is a good choice for Retina screens), but it also does not consistently scale the entirety of Firefox. <br />
<br />
If Firefox is not scaling fonts, you may want to create {{ic|userChrome.css}} and add appropriate styles to it. More information about {{ic|userChrome.css}} at [http://kb.mozillazine.org/index.php?title=UserChrome.css mozillaZine]. Starting from Firefox 69 the {{ic|userChrome.css}} and {{ic|userContent.css}} files are not loaded by default unless preference is set by the user. Open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|True}}, then restart Firefox to apply the changes.<br />
<br />
{{hc|~/.mozilla/firefox/<em><profile></em>/chrome/userChrome.css|<br />
@namespace url("https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");<br />
<br />
/* #tabbrowser-tabs, #navigator-toolbox, menuitem, menu, ... */<br />
* {<br />
font-size: 15px !important;<br />
}<br />
<br />
/* exception for badge on adblocker */<br />
.toolbarbutton-badge {<br />
font-size: 8px !important;<br />
}<br />
}}<br />
<br />
{{Warning|The AutoHiDPI extension is not compatible with Firefox Quantum (version 57 and above).}}<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use [https://github.com/ertug/autohidpi AutoHiDPI] add-on in order to automatically adjust {{ic|layout.css.devPixelsPerPx}} setting for the active screen. Also, since Firefox version 49, it auto-scales based on your screen resolution, making it easier to deal with 2 or more screens. For users of Firefox version 57 and above, the [https://addons.mozilla.org/firefox/addon/ffreszoom/ ffreszoom] add-on will adjust the page zoom if it detects you are using a large monitor (zoom level and threshold are configurable). Modifying the internal CSS DPI setting from an extension is currently unsupported [https://bugzilla.mozilla.org/show_bug.cgi?id=1373607].<br />
<br />
If you use Wayland, see [[Firefox#Wayland]] for instructions to enable the optional Wayland backend on {{pkg|firefox}}. This is also appicable to {{pkg|thunderbird}}.<br />
<br />
==== Chromium / Google Chrome ====<br />
<br />
Chromium should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--force-device-scale-factor}} flag with a scaling value. This will scale all content and ui, including tab and font size. For example {{ic|1=chromium --force-device-scale-factor=2}}.<br />
<br />
Using this option, a scaling factor of 1 would be normal scaling. Floating point values can be used. To make the change permanent, for Chromium, you can add it to {{ic|~/.config/chromium-flags.conf}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|2=<br />
--force-device-scale-factor=2<br />
}}<br />
<br />
To make this work for Chrome, add the same option to {{ic|~/.config/chrome-flags.conf}} instead.<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use the [https://chrome.google.com/webstore/detail/resolution-zoom/enjjhajnmggdgofagbokhmifgnaophmh reszoom] extension in order to automatically adjust the zoom level for the active screen.<br />
<br />
If using Wayland session, you should [[Chromium#Native_Wayland_support|enable]] native wayland support to avoid blurriness. See also [[Chromium#Incorrect HiDPI rendering]].<br />
<br />
==== Opera ====<br />
<br />
Opera should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--alt-high-dpi-setting=X}} command line option, where X is the desired DPI. For example, with {{ic|1=--alt-high-dpi-setting=144}} Opera will assume that DPI is 144. Newer versions of opera will auto detect the DPI using the font DPI setting (in KDE: the force font DPI setting.)<br />
<br />
=== Gimp 2.10 ===<br />
<br />
To fix toolbar icon sizes, update {{ic|1=Preferences->Interface->Icon Theme->Custom icon size}} to {{ic|1=huge}} or other value.<br />
<br />
If menu fonts are still too small you can update an existing theme by copying it from {{ic|/usr/share/gimp/2.0/themes}} into {{ic|~/.config/GIMP/2.10/themes/}} and changing {{ic|gtk-font-name}} and {{ic|font_name}} in {{ic|gtkrc}} into something bigger like {{ic|1=Sans 30}}. Then select the new theme from ''Preferences > Interface > Theme''. When copying make sure to rename the new directory into something different from the original name (example ''Dark > DarkHighDPI'').<br />
<br />
You can also try using [https://github.com/jedireza/gimp-hidpi gimp-hidpi] (installation instructions are outdated and refer to version 2.8, in Gimp 2.10 the theme should be installed into {{ic|~/.config/GIMP/2.10/themes/}})<br />
<br />
=== Inkscape ===<br />
<br />
To scale the icons to a "usable" size go to ''Preferences > Interface'' and set the icon size to Large or Larger[https://web.archive.org/web/20171118050743/http://www.inkscapeforum.com/viewtopic.php?t=18684][https://wiki.inkscape.org/wiki/index.php/HiDPI].<br />
<br />
=== Java applications ===<br />
<br />
==== AWT/Swing ====<br />
<br />
Java applications using the ''AWT/Swing'' framework can be scaled by defining the {{ic|sun.java2d.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, or a float value. For example,<br />
<br />
java -Dsun.java2d.uiScale=2 -jar some_swing_application.jar<br />
java -Dsun.java2d.uiScale=300% -jar some_swing_application.jar<br />
<br />
Since Java 9 the {{ic|GDK_SCALE}} environment variable is used to scale Swing applications accordingly.<br />
<br />
Note that at this point, Java ''AWT/Swing'' (up to including OpenJDK 13) only effectively supports integer values. A setting of {{ic|1=-Dsun.java2d.uiScale=250%}} or {{ic|1=GDK_SCALE=2.5}} will be treated as if it were set to {{ic|1=-Dsun.java2d.uiScale=2}} resp. {{ic|1=GDK_SCALE=2}}.<br />
<br />
==== JavaFX ====<br />
<br />
Java applications using ''JavaFX'' can be scaled by defining the {{ic|glass.gtk.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, an integer DPI value (where {{ic|96dpi}} represents a scale factor of {{ic|100%}}, and for example {{ic|192dpi}} represents a scale factor of {{ic|200%}}), or a float value. For example,<br />
<br />
java -Dglass.gtk.uiScale=200% -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=192dpi -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=2.0 -jar some_jfx_application.jar<br />
<br />
''JavaFX'' perfectly well supports fractions. Using values like {{ic|1=-Dglass.gtk.uiScale=250%}} or {{ic|1=-Dglass.gtk.uiScale=2.5}} will deliver the expected result.<br />
<br />
==== Mixed AWT/Swing and JavaFX ====<br />
<br />
Some Java applications mix ''JavaFX'' and ''AWT/Swing'' (via {{ic|javafx.embed.swing.JFXPanel}}). In that case, the settings for ''AWT/Swing'' will also affect ''JavaFX'', and setting {{ic|-Dglass.gtk.uiScale}} will have no effect.<br />
<br />
==== IntelliJ IDEA ====<br />
<br />
IntelliJ IDEA supports two HiDPI modes (JRE-managed and IDE-managed). The sequence for determining system scale factor is well documented at [https://intellij-support.jetbrains.com/hc/en-us/articles/360007994999-HiDPI-configuration]:<br />
<br />
# Java property – {{ic|-Dsun.java2d.uiScale}}<br />
# {{man|1|gsettings}} – {{ic|ubuntu.user-interface/scale-factor}} or {{ic|org.gnome.desktop.interface/scaling-factor}}<br />
# {{ic|GDK_SCALE}} and {{ic|GDK_DPI_SCALE}}<br />
# [[Xresources]] – {{ic|Xft.dpi}}<br />
# 1.0<br />
<br />
For troubleshooting, consult the "Show HiDPI Info" dialog via [https://www.jetbrains.com/help/idea/searching-everywhere.html search everywhere "Shift Shift"].<br />
<br />
When using per-monitor scaling, an issue might occur where IntelliJ fails to recognize the real, original monitor resolution. <br />
To remediate this problem some people have success by adding the {{ic|1=-Dsun.java2d.uiScale.enabled=true}} option to the {{ic|idea64.vmoptions}} file (''Help > Edit custom VM options''). <br />
<br />
If this does not work, the experimental GTK option {{ic|scale-monitor-framebuffer}} might be enabled on Wayland ([[#Wayland|see above]]). Currently JetBrains products run on xwayland and thus [https://youtrack.jetbrains.com/issue/IDEA-228070 have no native wayland support yet]. This makes the rendering in JetBrains products incompatible with the monitor scaling framebuffer. Disabling the framebuffer thus might solve blurry font/rendering issues for JB products, but alas results in disabled fractional scaling.<br />
<br />
=== LibreOffice ===<br />
<br />
[[LibreOffice]] on all VCL backends take setting from there respective toolkits. There is a bug where the {{ic|kf5}} backend on Wayland does not scale [https://bugs.documentfoundation.org/show_bug.cgi?id=138520]. Use the {{ic|gtk3}} VCL backend instead.<br />
<br />
=== MATLAB ===<br />
<br />
Recent versions (R2017b) of [[MATLAB]] allow to set the scale factor[https://www.mathworks.com/matlabcentral/answers/406956-does-matlab-support-high-dpi-screens-on-linux]:<br />
<br />
>> s = settings;s.matlab.desktop.DisplayScaleFactor<br />
>> s.matlab.desktop.DisplayScaleFactor.PersonalValue = 2<br />
<br />
The settings take effect after MATLAB is restarted.<br />
<br />
This can become tedious if you need to change the scaling frequently. To simplify this, consider using the following script:<br />
<br />
{{hc|~/bin/matlab-scale|2=<br />
#!/bin/sh<br />
exec matlab -r "s = settings;s.matlab.desktop.DisplayScaleFactor.PersonalValue=$1;quit"<br />
}}<br />
<br />
To change the display scaling to 3:<br />
<br />
$ matlab-scale 3<br />
<br />
=== Mono applications ===<br />
<br />
According to [https://bugzilla.xamarin.com/35/35870/bug.html], Mono applications should be scalable like [[#GDK 3 (GTK 3)|GTK 3]] applications. The precise method depends on the GUI library: GtkSharp obviouslys points back to Gtk, while the usual Windows Forms (libgdiplus) simply detects Xft settings.<br />
<br />
=== NetBeans ===<br />
<br />
NetBeans allows the font size of its interface to be controlled using the {{ic|1=--fontsize}} parameter during startup. To make this change permanent edit the {{ic|1=/usr/share/netbeans/etc/netbeans.conf}} file and append the {{ic|1=--fontsize}} parameter to the {{ic|1=netbeans_default_options}} property.[https://web.archive.org/web/20210117211145/http://wiki.netbeans.org/FaqFontSize]<br />
<br />
The editor fontsize can be controlled from ''Tools > Option > Fonts & Colors''.<br />
<br />
The output window fontsize can be controlled from ''Tools > Options > Miscelaneous > Output''<br />
<br />
=== OBS Studio ===<br />
<br />
Start obs with the environment variable {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} to disable [https://doc.qt.io/qt-5/highdpi.html#migrate-existing-applications Qt’s hi-dpi migration mode]. It is partially buggy (preview window can disappear after first start, depending on window position) and prevents OBS Studio from capturing at native resolution.<br />
<br />
The downside of this option is that the UI elements will now be messed up. To mitigate this, install the Yami theme, which works well on hi-dpi displays:<br />
<br />
{{Accuracy|Installation from archive other than the source of the {{Pkg|obs-studio}} package is not supported.}}<br />
<br />
$ wget https://github.com/obsproject/obs-studio/archive/fd256a46837033b9a4632327ece3c572bcb3b9b1.tar.gz -O /tmp/yami.tar.gz<br />
$ cd ~/.config/obs-studio<br />
$ tar xf /tmp/yami.tar.gz --strip-components=3 --wildcards '*/UI/data/themes/Yami*'<br />
<br />
Then, open File → Settings → General → Theme and chose Yami.<br />
<br />
=== Skype ===<br />
<br />
Skype for Linux ({{AUR|skypeforlinux-stable-bin}} package) uses [[#GDK 3 (GTK 3)]].<br />
<br />
=== Spotify ===<br />
<br />
You can change scale factor by simple {{ic|Ctrl++}} for zoom in, {{ic|Ctrl+-}} for zoom out and {{ic|Ctrl+0}} for default scale. Scaling setting will be saved in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, you may have to create this file by yourself:<br />
<br />
{{hc|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs|2=<br />
app.browser.zoom-level=100<br />
}}<br />
<br />
Also Spotify can be launched with a custom scaling factor which will be multiplied with setting specified in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, for example<br />
<br />
$ spotify --force-device-scale-factor=1.5<br />
<br />
=== Steam ===<br />
<br />
==== Official HiDPI support ====<br />
<br />
* Starting on 25 of January 2018 in the beta program there is actual support for HiDPI and it should be automatically detected.<br />
* ''Steam > Settings > Interface'', check "Enlarge text and icons based on monitor size" (restart required)<br />
* If it is not automatically detected, use {{ic|1=GDK_SCALE=2}} to set the desired scale factor.<br />
<br />
==== Unofficial ====<br />
<br />
The [https://github.com/MoriTanosuke/HiDPI-Steam-Skin HiDPI-Steam-Skin] can be installed to increase the font size of the interface. While not perfect, it does improve usability. <br />
<br />
{{Note|The README for the HiDPI skin lists several possible locations for where to place the skin. The correct folder out of these can be identified by the presence of a file named {{ic|1=skins_readme.txt}}.}}<br />
<br />
[https://steamcommunity.com/groups/metroskin/discussions/0/517142253861033946/ MetroSkin Unofficial Patch] also helps with HiDPI on Steam with Linux.<br />
<br />
=== Sublime Text 3 ===<br />
<br />
Sublime Text 3 has full support for display scaling. Go to ''Preferences > Settings > User Settings'' and add {{ic|"ui_scale": 2.0}} to your settings.<br />
<br />
=== Thunderbird ===<br />
<br />
See [[#Firefox]]. To access {{ic|about:config}}, go to ''Edit > Preferences > Advanced >Config editor''.<br />
<br />
=== VirtualBox ===<br />
<br />
{{Note|This only applies to KDE with scaling enabled.}}<br />
<br />
VirtualBox also applies the system-wide scaling to the virtual monitor, which reduces the maximum resolution inside VMs by your scaling factor (see [https://www.virtualbox.org/ticket/16604]).<br />
<br />
This can be worked around by calculating the inverse of your scaling factor and manually setting this new scaling factor for the VirtualBox execution, e.g.<br />
<br />
$ QT_SCALE_FACTOR=0.5 VirtualBox --startvm vm-name<br />
<br />
=== Wine applications ===<br />
<br />
Run<br />
<br />
$ winecfg<br />
<br />
and change the "dpi" setting found in the "Graphics" tab. This only affects the font size.<br />
<br />
=== Zathura document viewer ===<br />
<br />
No modifications required for document viewing.<br />
<br />
UI text scaling is specified via [https://pwmt.org/projects/zathura/documentation/ configuration file] (note that "font" is a [https://pwmt.org/projects/girara/options/ girara option]):<br />
<br />
set font "monospace normal 20"<br />
<br />
=== Zoom ===<br />
<br />
Set the {{ic|scaleFactor}} variable in {{ic|~/.config/zoomus.conf}}.<br />
<br />
For the Flatpak version, set the environment variable {{ic|QT_SCALE_FACTOR}} (e.g. to 0.5 [https://old.reddit.com/r/Zoom/comments/hat5af/linux_client_ui_elements_too_large_after_update/]). This can be easily done with [https://flathub.org/apps/details/com.github.tchx84.Flatseal Flatseal], if using a GUI tool is preferred.<br />
<br />
=== Gazebo ===<br />
<br />
Gazebo only renders an upper left of a view instead of the whole view. To fix this a Qt enviorment variable must be set.<br />
To run Gazebo:<br />
$ QT_SCREEN_SCALE_FACTORS=[1.0] gazebo<br />
To run a ROS simulation:<br />
$ TURTLEBOT3_MODEL=burger QT_SCREEN_SCALE_FACTORS=[1.0] roslaunch turtlebot3_gazebo turtlebot3_world.launch<br />
Making an alias such as gazebo="QT_SCREEN_SCALE_FACTORS=[1.0] gazebo" works for the first case but not for the second.<br />
<br />
=== Fcitx ===<br />
<br />
Fcitx preedit {{ic|FontSize}} can be changed in {{ic|~/.config/fcitx/conf/fcitx-classic-ui.config}}.<br />
<br />
=== Unsupported applications ===<br />
<br />
{{AUR|run_scaled-git}} can be used to scale applications (which uses {{Pkg|xpra}} internally).<br />
<br />
Another approach is to run the application full screen and without decoration in its own VNC desktop. Then scale the viewer. With Vncdesk ({{AUR|vncdesk-git}} from the [[AUR]]) you can set up a desktop per application, then start server and client with a simple command such as {{ic|vncdesk 2}}.<br />
<br />
[[x11vnc]] has an experimental option {{ic|-appshare}}, which opens one viewer per application window. Perhaps something could be hacked up with that.<br />
<br />
== Multiple displays ==<br />
<br />
The HiDPI setting applies to the whole desktop, so non-HiDPI external displays show everything too large. However, note that setting different scaling factors for different monitors is already supported in [[Wayland]].<br />
<br />
=== Side display ===<br />
<br />
One workaround is to use [[xrandr]]'s scale option. To have a non-HiDPI monitor (on DP1) right of an internal HiDPI display (eDP1), one could run:<br />
<br />
$ xrandr --output eDP-1 --auto --output DP-1 --auto --scale 2x2 --right-of eDP-1<br />
<br />
When extending above the internal display, you may see part of the internal display on the external monitor. In that case, specify the position manually.<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
{{Note|1=Above solution with {{ic|--scale 2x2}} does not work on some Nvidia cards. No solution is currently available. [https://bbs.archlinux.org/viewtopic.php?pid=1670840] A potential workaround exists with configuring {{ic|1=ForceFullCompositionPipeline=On}} on the {{ic|CurrentMetaMode}} via {{ic|nvidia-settings}}. For more info see [https://askubuntu.com/a/979551].}}<br />
<br />
{{Note|If you are using the {{ic|modesetting}} driver you will get mouse flickering. This can be solved by scaling your non-scaled screen by 0.9999x0.9999.}}<br />
<br />
=== Multiple external monitors ===<br />
<br />
There might be some problems in scaling more than one external monitors which have lower dpi than the built-in HiDPI display. In that case, you may want to try downscaling the HiDPI display instead, with e.g.<br />
<br />
$ xrandr --output eDP1 --scale 0.5x0.5 --output DP2 --right-of eDP1 --output HDMI1 --right-of DP2<br />
<br />
In addition, when you downscale the HiDPI display, the font on the HiDPI display will be slightly blurry, but it's a different kind of bluriness compared with the one introduced by upscaling the external displays. You may compare and see which kind of bluriness is less problematic for you.<br />
<br />
=== Mirroring ===<br />
<br />
If all you want is to mirror ("unify") displays, this is easy as well:<br />
<br />
With AxB your native HiDPI resolution (for ex 3200x1800) and CxD your external screen resolution (e.g. 1920x1200)<br />
<br />
$ xrandr --output HDMI --scale [A/C]x[B/D]<br />
<br />
In this example which is QHD (3200/1920 = 1.66 and 1800/1200 = 1.5)<br />
<br />
$ xrandr --output HDMI --scale 1.66x1.5<br />
<br />
For UHD to 1080p (3840/1920=2 2160/1080=2)<br />
<br />
$ xrandr --output HDMI --scale 2x2<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
=== Tools ===<br />
<br />
There are several tools which automate the commands described above.<br />
<br />
* [https://gist.github.com/wvengen/178642bbc8236c1bdb67 This script] extend a non-HiDPI external display above a HiDPI internal display.<br />
* [https://github.com/ashwinvis/xrandr-extend xrandr-extend].<br />
* {{AUR|xlayoutdisplay}} is a CLI front end for xrandr which detects and sets correct DPI: [https://github.com/alex-courtis/xlayoutdisplay README]<br />
<br />
== Linux console ==<br />
<br />
The [[w:Linux console|Linux console]] changes the font to {{ic|TER16x32}} (based on {{ic|ter-i32b}} from {{Pkg|terminus-font}}[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ac8b6f148fc97e9e10b48bd337ef571b1d1136aa]) accordingly based on the resolution of the display. If your monitor is not recognised as HiDPI, the default font can be changed. In that case, specify {{ic|1=fbcon=font:TER16x32}} in the [[kernel command line]].<br />
<br />
=== Fonts outside the kernel ===<br />
<br />
The largest fonts present in the {{Pkg|kbd}} package are {{ic|latarcyrheb-sun32}} and {{ic|solar24x32}}. Other packages like {{Pkg|terminus-font}} contain further alternatives, such as {{ic|ter-132n}} (normal) and {{ic|ter-132b}} (bold). See [[Linux console#Fonts]] for configuration details and [[Linux console#Persistent configuration]] in particular for applying the font setting during the early userspace boot sequence.<br />
<br />
After changing the font, it is often garbled and unreadable when changing to other virtual consoles ({{ic|tty2-6}}). To fix this you can [[Kernel_mode_setting#Forcing_modes_and_EDID|force specific mode]] for KMS, such as {{ic|1=video=2560x1600@60}} (substitute in the native resolution of your HiDPI display), and reboot.<br />
<br />
Users booting though [[UEFI]] may experience the console and [[boot loader]] being constrained to a low resolution despite correct [[KMS]] settings being set. This can be caused by legacy/BIOS boot being enabled in UEFI settings. Disabling legacy boot to bypass the compatibility layer should allow the system to boot at the correct resolution.<br />
<br />
== See also ==<br />
<br />
* [https://www.phoronix.com/scan.php?page=article&item=linux_uhd4k_gpus Ultra HD 4K Linux Graphics Card Testing] (Nov 2013)<br />
* [https://www.eizo.com/library/basics/pixel_density_4k/ Understanding pixel density]<br />
* [http://wok.oblomov.eu/tecnologia/mixed-dpi-x11/ Mixed DPI and the X Window System]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=HiDPI&diff=707944HiDPI2021-12-29T17:26:16Z<p>Thiagowfx: /* GUI toolkits */ s/vym/clementine - use a qt application that's more likely to be installed</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:HiDPI]]<br />
[[zh-hans:HiDPI]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related articles end}}<br />
HiDPI (High Dots Per Inch) displays, also known by Apple's "[[wikipedia:Retina Display|Retina Display]]" marketing name, are screens with a high resolution in a relatively small format. They are mostly found in high-end laptops and monitors.<br />
<br />
Not all software behaves well in high-resolution mode yet. Here are listed most common tweaks which make work on a HiDPI screen more pleasant.<br />
<br />
== Desktop environments ==<br />
<br />
=== GNOME ===<br />
<br />
To enable HiDPI, navigate to ''Settings > Devices > Displays > Scale'' and choose an appropriate value. Or, use gsettings:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "[{'Gdk/WindowScalingFactor', <2>}]"<br />
$ gsettings set org.gnome.desktop.interface scaling-factor 2<br />
<br />
{{Note|1=GNOME only allows integer scaling numbers to be set. 1 = 100%, 2 = 200%, etc. See [[#Fractional scaling]] below.}}<br />
<br />
==== Fractional scaling ====<br />
<br />
A setting of {{ic|2, 3, etc}}, which is all you can do with {{ic|scaling-factor}}, may not be ideal for certain HiDPI displays and smaller screens (e.g. small tablets). Fractional scaling is possible on both Wayland and Xorg, though the process differs.<br />
<br />
===== Wayland =====<br />
<br />
Enable the experimental fractional scaling feature:<br />
<br />
$ gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"<br />
<br />
then open ''Settings > Devices > Displays'' (the new options may only appear after a restart).<br />
<br />
{{Note|Enabling fractional scaling can result in blur for legacy applications using XWayland, ''even if only integer scales are used'', because the rendering method changes.}}<br />
<br />
To enable the option for all users, create the following three files with the corresponding content<br />
<br />
{{hc|/etc/dconf/profile/user|<nowiki><br />
user-db:user<br />
system-db:local<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/local.d/00-hidpi|<nowiki><br />
[org/gnome/mutter]<br />
experimental-features=['scale-monitor-framebuffer']<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/locks/hidpi|<nowiki><br />
/org/gnome/mutter/experimental-features<br />
</nowiki>}}<br />
<br />
Then run {{ic|dconf update}} and restart the machine. This will permanently lock the option.<br />
<br />
===== Xorg =====<br />
<br />
You can achieve any non-integer scale factor by using a combination of GNOME's {{ic|scaling-factor}} and [[xrandr]]. This combination keeps the TTF fonts properly scaled so that they do not become blurry if using {{ic|xrandr}} alone. You specify zoom-in factor with {{ic|gsettings}} and zoom-out factor with [[xrandr]].<br />
<br />
First scale GNOME up to the minimum size which is too big. Usually "2" is already too big, otherwise try "3" etc. Then start scaling down by setting zoom-out factor with [[xrandr]]. First get the relevant output name, the examples below use {{ic|eDP1}}. Start e.g. with zoom-out 1.25 times. If the UI is still too big, increase the scale factor; if it is too small decrease the scale factor.<br />
<br />
$ xrandr --output eDP1 --scale 1.25x1.25<br />
<br />
{{Note|To allow the mouse to reach the whole screen, you may need to use the {{ic|--panning}} option as explained in [[#Side display]].}}<br />
<br />
To ensure that the settings persist across reboots, you may choose to use {{Pkg|autorandr}}. Refer to [https://askubuntu.com/a/1130337 this StackOverflow] for more information.<br />
<br />
{{Accuracy|The following was initially added under [[#X Resources]]. Clarify how it integrates with the info there or that above for GNOME.|section=GNOME ignores X settings}}<br />
<br />
GNOME ignores X settings due to its xsettings Plugin in Gnome Settings Daemon, where DPI setting is hard coded.<br />
There is blog entry for [http://blog.drtebi.com/2012/12/changing-dpi-setting-on-gnome-34.html recompiling Gnome Settings Daemon].<br />
In the source documentation there is another way mentioned to set X settings DPI:<br />
<br />
You can use the gsettings, just make sure to read previous setting first and merge it. In just simply set it with this command:<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Xft/DPI': <153600>}"<br />
<br />
From README.xsettings<br />
<br />
Noting that variants must be specified in the usual way (wrapped in <>).<br />
<br />
Note also that DPI in the above example is expressed in 1024ths of an inch.<br />
<br />
==== Text Scaling ====<br />
<br />
Alternatively, or in addition to changing the display scaling, you can separately scale text. This can be done by navigating to ''Fonts > Scaling Factor'' in Gnome Tweaks, or using gsettings. Note that the text scaling factor need not be limited to whole integers, for example:<br />
<br />
$ gsettings set org.gnome.desktop.interface text-scaling-factor 1.5<br />
<br />
===== GTK+ vs Gnome Shell elements on Xorg =====<br />
<br />
Adjusting the text scaling as per the above only affects GTK+ elements of the GNOME desktop. This should cover everything on Wayland. However, those on an Xorg session may find that they need to make further adjustments on HiDPI environments, since the GNOME Shell UI (including the top bar, dock, application menus, etc.) relies separately on the [https://developer.gnome.org/st/stable/ St]{{Dead link|2021|11|11|status=404}} toolkit. Note that this is a long-standing issue to which a [https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/486 patch] has been merged and available for Gnome Shell 3.35 onward. For older releases, Xorg users can resolve most of the Gnome shell scaling problems by manually editing the shell theme that they are currently using. The relevant CSS files are normally located at {{ic|/usr/share/themes/YOUR-THEME/gnome-shell/gnome-shell.css}}. Users should increase all "font-size" elements in this file in proportion to their display scaling (doubling font sizes for 200% scaling, etc.) For example, the top of an edited CSS file for the [https://github.com/adapta-project/adapta-gtk-theme Adapta] shell theme might look like:<br />
<br />
{{hc|usr/share/themes/Adapta/gnome-shell/gnome-shell.css|2=<br />
stage { font-size: 20pt; font-family: Roboto, Noto Sans, Sans-Serif; color: #263238; }<br />
}}<br />
<br />
Once these changes have been saved, activate them by switching to another theme (for example, using {{pkg|gnome-tweaks}}) and then reverting back again. The top bar, application menus, calendar, and other shell elements should now be correctly scaled.<br />
<br />
In addition to editing the relevant shell theme's CSS file, users on Xorg may also wish to increase the title bar font at the top of open applications. This can be done through the dconf editor ({{ic|org > gnome > desktop > wm > preferences :: titlebar-font}}). Note that the {{ic|title-bar-uses-system-fonts}} option should also be turned off. Alternatively, use gsettings:<br />
<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-font 'Cantarell Bold 22' ## Change as needed<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-uses-system-font false<br />
<br />
=== KDE Plasma ===<br />
<br />
You can use Plasma's settings to fine tune font, icon, and widget scaling. This solution affects both Qt and GTK applications.<br />
<br />
To adjust font, widget, and icon scaling together:<br />
<br />
# ''System Settings > Display and Monitor > Display Configuration > Global Scale''<br />
# Drag the slider to the desired size<br />
# Restart for the settings to take effect<br />
<br />
To adjust only font scaling:<br />
<br />
# ''System Settings > Fonts''<br />
# Check "Force fonts DPI" and adjust the DPI level to the desired value. This setting should take effect immediately for newly started applications. You will have to logout and login for it to take effect on Plasma desktop.<br />
<br />
To adjust only icon scaling:<br />
<br />
# ''System Settings > Icons > Advanced''<br />
# Choose the desired icon size for each category listed. This should take effect immediately.<br />
<br />
==== Tray icons with fixed size ====<br />
<br />
The tray icons are not scaled with the rest of the desktop, since Plasma ignores the Qt scaling settings by default. To make Plasma respect the Qt settings, [[Environment variables|set]] {{ic|1=PLASMA_USE_QT_SCALING=1}}.<br />
<br />
=== Xfce ===<br />
<br />
Xfce supports HiDPI scaling which can be enabled using the settings manager:<br />
<br />
# Go to ''Settings Manager > Appearance > Settings > Window Scaling'' and select 2 as the scaling factor.<br />
# Go to ''Settings Manager > Window Manager > Style'' and select {{ic|Default-xhdpi}} theme.<br />
<br />
Alternatively, it is possible to do the same from command line using {{ic|xfconf-query}}:<br />
<br />
xfconf-query -c xsettings -p /Gdk/WindowScalingFactor -s 2<br />
xfconf-query -c xfwm4 -p /general/theme -s Default-xhdpi<br />
<br />
After either of the above changes, fonts in some GTK applications may still not be scaled; you may additionally do the following (see [[#GDK 3 (GTK 3)]]):<br />
<br />
# Go to ''Settings Manager > Appearance > Fonts > Custom DPI setting'' and change from 96 to 192<br />
# Set the environment variable {{ic|1=GDK_DPI_SCALE=0.5}} (e.g. in {{ic|~/.profile}}) to un-scale some fonts that would be scaled twice<br />
<br />
The steps above would set 2x scaled resolution for Xfce and other GTK 3 apps.<br />
<br />
Scaling for Qt 5 apps should be set manually, see [[#Qt 5]]. Note that if you set a Custom DPI for fonts above, you likely need to set {{ic|1=QT_FONT_DPI=96}} to avoid double-scaling of fonts in Qt applications.<br />
<br />
=== Cinnamon ===<br />
<br />
Has good support out of the box.<br />
<br />
=== Enlightenment ===<br />
<br />
For E18, go to the E Setting panel. In ''Look > Scaling'', you can control the UI scaling ratios. A ratio of 1.2 seems to work well for the native resolution of the MBPr 15" screen.<br />
<br />
== X Resources ==<br />
<br />
If you are not using a desktop environment such as KDE, Xfce, or other that manipulates the X settings for you, you can set the desired DPI setting manually via the {{ic|Xft.dpi}} variable in [[Xresources]]:<br />
<br />
{{hc|~/.Xresources|2=<br />
Xft.dpi: 192<br />
<br />
! These might also be useful depending on your monitor and personal preference:<br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintfull<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
}}<br />
<br />
For {{ic|Xft.dpi}}, using integer multiples of 96 usually works best, e.g. 192 for 200% scaling.<br />
<br />
Make sure the settings are loaded properly when X starts, for instance in your {{ic|~/.xinitrc}} with {{ic|xrdb -merge ~/.Xresources}} (see [[Xresources]] for more information).<br />
<br />
This will make the font render properly in most toolkits and applications, it will however not affect things such as icon size!<br />
Setting {{ic|Xft.dpi}} at the same time as toolkit scale (e.g. {{ic|GDK_SCALE}}) may cause interface elements to be much larger than intended in some programs like firefox.<br />
<br />
== X Server ==<br />
<br />
{{Accuracy|{{Pkg|libxft}} is a ''font rendering interface library'', the {{ic|Xft.dpi}} setting was not intended to be abused by other applications. On the other hand, the {{ic|xorg.conf}} value should affect everything.}}<br />
<br />
Some programs may still interpret the DPI given by the X server (most interpret X Resources, though, directly or indirectly). Older versions of i3 (before 2017) and Chromium (before 2017) used to do this.<br />
<br />
To verify that the X Server has properly detected the physical dimensions of your monitor, use the ''xdpyinfo'' utility from the {{Pkg|xorg-xdpyinfo}} package:<br />
<br />
{{hc|$ xdpyinfo {{!}} grep -B 2 resolution|<br />
screen #0:<br />
dimensions: 3200x1800 pixels (423x238 millimeters)<br />
resolution: 192x192 dots per inch<br />
}}<br />
<br />
This example uses inaccurate dimensions (423mm x 328mm, even though the Dell XPS 9530 has 346mm x 194mm) to have a clean multiple of 96 dpi, in this case 192 dpi. This tends to work better than using the correct DPI — Pango renders fonts crisper in i3 for example.<br />
<br />
If the DPI displayed by xdpyinfo is not correct, see [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
== GUI toolkits ==<br />
<br />
=== Qt 5 ===<br />
<br />
Since Qt 5.6, Qt 5 applications can be instructed to honor screen DPI by setting the {{ic|QT_AUTO_SCREEN_SCALE_FACTOR}} environment variable:<br />
<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=1<br />
<br />
If automatic detection of DPI does not produce the desired effect, scaling can be set manually per-screen ({{ic|QT_SCREEN_SCALE_FACTORS}}) or globally ({{ic|QT_SCALE_FACTOR}}). For more details see the [https://blog.qt.io/blog/2016/01/26/high-dpi-support-in-qt-5-6/ Qt blog post] or [https://doc.qt.io/qt-5/highdpi.html Qt developer documentation].<br />
<br />
{{Note|<br />
* If you manually set the screen factor, it is important to set {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} otherwise some applications which explicitly force high DPI enabling get scaled twice.<br />
* {{ic|QT_SCALE_FACTOR}} scales fonts, but {{ic|QT_SCREEN_SCALE_FACTORS}} does not scale fonts.<br />
* If you also set the font DPI manually in ''xrdb'' to support other toolkits, {{ic|QT_SCALE_FACTORS}} will give you huge fonts.<br />
* If you have multiple screens of differing DPI ie: [[#Side display]] you may need to do {{ic|1=QT_SCREEN_SCALE_FACTORS="2;2"}}<br />
}}<br />
<br />
An [https://bugreports.qt.io/browse/QTBUG-53022 alternative] is e.g.:<br />
<br />
QT_FONT_DPI=96 clementine<br />
<br />
=== GDK 3 (GTK 3) ===<br />
<br />
{{Note|As stated in the [[#X Resources]] section, if you have xft.dpi set to a larger dpi, it will make other scales larger than usual, including GDK.}} <br />
<br />
Setting the GDK scale will scale the UI, however it will not scale icons. If you are using a minimal window manager where you are setting the dpi via Xft.dpi, GDK should scale perfectly fine with it. In other cases, [https://developer.gnome.org/gtk3/stable/gtk-x11.html do the following]:<br />
<br />
To scale UI elements by an integer factor:<br />
<br />
$ export GDK_SCALE=2<br />
<br />
To undo scaling of text, fractional scale can be used:<br />
<br />
$ export GDK_DPI_SCALE=0.5<br />
<br />
=== GTK 2 ===<br />
<br />
Scaling of UI elements is not supported by the toolkit itself, however it's possible to generate a theme with elements pre-scaled for HiDPI display using {{AUR|themix-full-git}}.<br />
<br />
=== Electron ===<br />
<br />
[https://electronjs.org/ Electron] applications (e.g. {{AUR|slack-desktop}}, {{pkg|signal-desktop}}, etc.) can be configured to use a custom scaling value by adding a {{ic|1=--force-device-scale-factor}} flag to the .desktop file. This is normally located at {{ic|/usr/share/applications/}}, and can normally be overridden on a per-user basis by copying it to {{ic|~/.local/share/applications}}. The flag should be added to the line beginning with "Exec=". For example:<br />
<br />
{{hc|/usr/share/applications/slack.desktop|2=<br />
Exec=env LD_PRELOAD=/usr/lib/libcurl.so.3 /usr/bin/slack --force-device-scale-factor=1.5 %U<br />
}}<br />
<br />
=== Elementary (EFL) ===<br />
<br />
To scale UI elements by a factor of 1.5:<br />
<br />
export ELM_SCALE=1.5<br />
<br />
For more details see https://phab.enlightenment.org/w/elementary/<br />
<br />
=== GNUstep ===<br />
<br />
GNUstep applications that use its gui (AppKit) library accept a {{ic|GSScaleFactor}} property in their defaults (STEP preferences). To define a scaling factor of 1.5 for all apps:<br />
<br />
defaults write NSGlobalDomain GSScaleFactor 1.5<br />
<br />
Some automatic detection was possible back in 2011, but the code responsible for the X11 backend was [https://github.com/gnustep/libs-back/commit/337ce46bba304732d9a7c7495a3dd245a3219660 commented out] thereafter.<br />
<br />
== Boot managers ==<br />
<br />
=== GRUB ===<br />
<br />
==== Lower the framebuffer resolution ====<br />
<br />
Set a lower resolution for the framebuffer as explained in [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
==== Change GRUB font size ====<br />
<br />
Find a ttf font that you like in {{ic|/usr/share/fonts/}}.<br />
<br />
Convert the font to a format that GRUB can utilize:<br />
<br />
# grub-mkfont -s 30 -o /boot/grubfont.pf2 /usr/share/fonts/FontFamily/FontName.ttf<br />
<br />
{{Note|Change the {{ic|-s 30}} parameter to modify the font size}}<br />
<br />
Edit {{ic|/etc/default/grub}} to set the new font as shown in [[GRUB/Tips and tricks#Background image and bitmap fonts]]:<br />
<br />
GRUB_FONT="/boot/grubfont.pf2"<br />
<br />
{{Note|{{ic|GRUB_THEME}} overrides {{ic|GRUB_FONT}} if it is used.}}<br />
<br />
Finally [[GRUB#Generate the main configuration file|regenerate the main configuration file]].<br />
<br />
{{Tip|The font size can also be changed with the GUI tool {{Pkg|grub-customizer}}.}}<br />
<br />
=== systemd-boot ===<br />
<br />
Adding the following line and running {{ic|bootctl update}} increases font-size in the [[systemd-boot#Loader_configuration|systemd-boot]] menu:<br />
<br />
{{hc|/boot/loader/loader.conf|2=<br />
console-mode 1<br />
}}<br />
<br />
== Applications ==<br />
<br />
If you are running a Wayland session, but application is running via Xwayland (either because it does not support Wayland natively or because it uses X11 by default), you could still get blurry fonts and interface, even if the application supports HiDPI. See [https://bugs.kde.org/show_bug.cgi?id=389191 this bug report]. See also [[Wayland#Detect Xwayland applications visually]].<br />
<br />
=== Atom ===<br />
<br />
Add {{ic|1=--force-device-scale-factor=2}} as a flag to the atom.desktop file:<br />
<br />
{{hc|/usr/share/applications/atom.desktop|2=<br />
Exec=/usr/bin/atom --force-device-scale-factor=2 %F<br />
}}<br />
<br />
=== Browsers ===<br />
<br />
==== Firefox ====<br />
<br />
Firefox should use the [[#GDK 3 (GTK 3)]] settings. However, the suggested {{ic|GDK_SCALE}} suggestion does not consistently scale the entirety of Firefox, and does not work for fractional values (e.g., a factor of 158DPI/96DPI = 1.65 for a 1080p 14" laptop). You may want to use {{ic|GDK_DPI_SCALE}} instead. Another option, which will avoid Firefox-specific settings in many setups is to use the settings in [[#X Resources]] as Firefox should respect the {{ic|Xft.dpi}} value defined there.<br />
<br />
To override those, open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|layout.css.devPixelsPerPx}} to {{ic|2}} (or find the one that suits you better; {{ic|2}} is a good choice for Retina screens), but it also does not consistently scale the entirety of Firefox. <br />
<br />
If Firefox is not scaling fonts, you may want to create {{ic|userChrome.css}} and add appropriate styles to it. More information about {{ic|userChrome.css}} at [http://kb.mozillazine.org/index.php?title=UserChrome.css mozillaZine]. Starting from Firefox 69 the {{ic|userChrome.css}} and {{ic|userContent.css}} files are not loaded by default unless preference is set by the user. Open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|True}}, then restart Firefox to apply the changes.<br />
<br />
{{hc|~/.mozilla/firefox/<em><profile></em>/chrome/userChrome.css|<br />
@namespace url("https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");<br />
<br />
/* #tabbrowser-tabs, #navigator-toolbox, menuitem, menu, ... */<br />
* {<br />
font-size: 15px !important;<br />
}<br />
<br />
/* exception for badge on adblocker */<br />
.toolbarbutton-badge {<br />
font-size: 8px !important;<br />
}<br />
}}<br />
<br />
{{Warning|The AutoHiDPI extension is not compatible with Firefox Quantum (version 57 and above).}}<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use [https://github.com/ertug/autohidpi AutoHiDPI] add-on in order to automatically adjust {{ic|layout.css.devPixelsPerPx}} setting for the active screen. Also, since Firefox version 49, it auto-scales based on your screen resolution, making it easier to deal with 2 or more screens. For users of Firefox version 57 and above, the [https://addons.mozilla.org/firefox/addon/ffreszoom/ ffreszoom] add-on will adjust the page zoom if it detects you are using a large monitor (zoom level and threshold are configurable). Modifying the internal CSS DPI setting from an extension is currently unsupported [https://bugzilla.mozilla.org/show_bug.cgi?id=1373607].<br />
<br />
If you use Wayland, see [[Firefox#Wayland]] for instructions to enable the optional Wayland backend on {{pkg|firefox}}. This is also appicable to {{pkg|thunderbird}}.<br />
<br />
==== Chromium / Google Chrome ====<br />
<br />
Chromium should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--force-device-scale-factor}} flag with a scaling value. This will scale all content and ui, including tab and font size. For example {{ic|1=chromium --force-device-scale-factor=2}}.<br />
<br />
Using this option, a scaling factor of 1 would be normal scaling. Floating point values can be used. To make the change permanent, for Chromium, you can add it to {{ic|~/.config/chromium-flags.conf}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|2=<br />
--force-device-scale-factor=2<br />
}}<br />
<br />
To make this work for Chrome, add the same option to {{ic|~/.config/chrome-flags.conf}} instead.<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use the [https://chrome.google.com/webstore/detail/resolution-zoom/enjjhajnmggdgofagbokhmifgnaophmh reszoom] extension in order to automatically adjust the zoom level for the active screen.<br />
<br />
If using Wayland session, you should [[Chromium#Native_Wayland_support|enable]] native wayland support to avoid blurriness. See also [[Chromium#Incorrect HiDPI rendering]].<br />
<br />
==== Opera ====<br />
<br />
Opera should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--alt-high-dpi-setting=X}} command line option, where X is the desired DPI. For example, with {{ic|1=--alt-high-dpi-setting=144}} Opera will assume that DPI is 144. Newer versions of opera will auto detect the DPI using the font DPI setting (in KDE: the force font DPI setting.)<br />
<br />
=== Gimp 2.10 ===<br />
<br />
To fix toolbar icon sizes, update {{ic|1=Preferences->Interface->Icon Theme->Custom icon size}} to {{ic|1=huge}} or other value.<br />
<br />
If menu fonts are still too small you can update an existing theme by copying it from {{ic|/usr/share/gimp/2.0/themes}} into {{ic|~/.config/GIMP/2.10/themes/}} and changing {{ic|gtk-font-name}} and {{ic|font_name}} in {{ic|gtkrc}} into something bigger like {{ic|1=Sans 30}}. Then select the new theme from ''Preferences > Interface > Theme''. When copying make sure to rename the new directory into something different from the original name (example ''Dark > DarkHighDPI'').<br />
<br />
You can also try using [https://github.com/jedireza/gimp-hidpi gimp-hidpi] (installation instructions are outdated and refer to version 2.8, in Gimp 2.10 the theme should be installed into {{ic|~/.config/GIMP/2.10/themes/}})<br />
<br />
=== Inkscape ===<br />
<br />
To scale the icons to a "usable" size go to ''Preferences > Interface'' and set the icon size to Large or Larger[https://web.archive.org/web/20171118050743/http://www.inkscapeforum.com/viewtopic.php?t=18684][https://wiki.inkscape.org/wiki/index.php/HiDPI].<br />
<br />
=== Java applications ===<br />
<br />
==== AWT/Swing ====<br />
<br />
Java applications using the ''AWT/Swing'' framework can be scaled by defining the {{ic|sun.java2d.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, or a float value. For example,<br />
<br />
java -Dsun.java2d.uiScale=2 -jar some_swing_application.jar<br />
java -Dsun.java2d.uiScale=300% -jar some_swing_application.jar<br />
<br />
Since Java 9 the {{ic|GDK_SCALE}} environment variable is used to scale Swing applications accordingly.<br />
<br />
Note that at this point, Java ''AWT/Swing'' (up to including OpenJDK 13) only effectively supports integer values. A setting of {{ic|1=-Dsun.java2d.uiScale=250%}} or {{ic|1=GDK_SCALE=2.5}} will be treated as if it were set to {{ic|1=-Dsun.java2d.uiScale=2}} resp. {{ic|1=GDK_SCALE=2}}.<br />
<br />
==== JavaFX ====<br />
<br />
Java applications using ''JavaFX'' can be scaled by defining the {{ic|glass.gtk.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, an integer DPI value (where {{ic|96dpi}} represents a scale factor of {{ic|100%}}, and for example {{ic|192dpi}} represents a scale factor of {{ic|200%}}), or a float value. For example,<br />
<br />
java -Dglass.gtk.uiScale=200% -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=192dpi -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=2.0 -jar some_jfx_application.jar<br />
<br />
''JavaFX'' perfectly well supports fractions. Using values like {{ic|1=-Dglass.gtk.uiScale=250%}} or {{ic|1=-Dglass.gtk.uiScale=2.5}} will deliver the expected result.<br />
<br />
==== Mixed AWT/Swing and JavaFX ====<br />
<br />
Some Java applications mix ''JavaFX'' and ''AWT/Swing'' (via {{ic|javafx.embed.swing.JFXPanel}}). In that case, the settings for ''AWT/Swing'' will also affect ''JavaFX'', and setting {{ic|-Dglass.gtk.uiScale}} will have no effect.<br />
<br />
==== IntelliJ IDEA ====<br />
<br />
IntelliJ IDEA supports two HiDPI modes (JRE-managed and IDE-managed). The sequence for determining system scale factor is well documented at [https://intellij-support.jetbrains.com/hc/en-us/articles/360007994999-HiDPI-configuration]:<br />
<br />
# Java property – {{ic|-Dsun.java2d.uiScale}}<br />
# {{man|1|gsettings}} – {{ic|ubuntu.user-interface/scale-factor}} or {{ic|org.gnome.desktop.interface/scaling-factor}}<br />
# {{ic|GDK_SCALE}} and {{ic|GDK_DPI_SCALE}}<br />
# [[Xresources]] – {{ic|Xft.dpi}}<br />
# 1.0<br />
<br />
For troubleshooting, consult the "Show HiDPI Info" dialog via [https://www.jetbrains.com/help/idea/searching-everywhere.html search everywhere "Shift Shift"].<br />
<br />
When using per-monitor scaling, an issue might occur where IntelliJ fails to recognize the real, original monitor resolution. <br />
To remediate this problem some people have success by adding the {{ic|1=-Dsun.java2d.uiScale.enabled=true}} option to the {{ic|idea64.vmoptions}} file (''Help > Edit custom VM options''). <br />
<br />
If this does not work, the experimental GTK option {{ic|scale-monitor-framebuffer}} might be enabled on Wayland ([[#Wayland|see above]]). Currently JetBrains products run on xwayland and thus [https://youtrack.jetbrains.com/issue/IDEA-228070 have no native wayland support yet]. This makes the rendering in JetBrains products incompatible with the monitor scaling framebuffer. Disabling the framebuffer thus might solve blurry font/rendering issues for JB products, but alas results in disabled fractional scaling.<br />
<br />
=== LibreOffice ===<br />
<br />
[[LibreOffice]] on all VCL backends take setting from there respective toolkits. There is a bug where the {{ic|kf5}} backend on Wayland does not scale [https://bugs.documentfoundation.org/show_bug.cgi?id=138520]. Use the {{ic|gtk3}} VCL backend instead.<br />
<br />
=== MATLAB ===<br />
<br />
Recent versions (R2017b) of [[MATLAB]] allow to set the scale factor[https://www.mathworks.com/matlabcentral/answers/406956-does-matlab-support-high-dpi-screens-on-linux]:<br />
<br />
>> s = settings;s.matlab.desktop.DisplayScaleFactor<br />
>> s.matlab.desktop.DisplayScaleFactor.PersonalValue = 2<br />
<br />
The settings take effect after MATLAB is restarted.<br />
<br />
This can become tedious if you need to change the scaling frequently. To simplify this, consider using the following script:<br />
<br />
{{hc|~/bin/matlab-scale|2=<br />
#!/bin/sh<br />
exec matlab -r "s = settings;s.matlab.desktop.DisplayScaleFactor.PersonalValue=$1;quit"<br />
}}<br />
<br />
To change the display scaling to 3:<br />
<br />
$ matlab-scale 3<br />
<br />
=== Mono applications ===<br />
<br />
According to [https://bugzilla.xamarin.com/35/35870/bug.html], Mono applications should be scalable like [[#GDK 3 (GTK 3)|GTK 3]] applications. The precise method depends on the GUI library: GtkSharp obviouslys points back to Gtk, while the usual Windows Forms (libgdiplus) simply detects Xft settings.<br />
<br />
=== NetBeans ===<br />
<br />
NetBeans allows the font size of its interface to be controlled using the {{ic|1=--fontsize}} parameter during startup. To make this change permanent edit the {{ic|1=/usr/share/netbeans/etc/netbeans.conf}} file and append the {{ic|1=--fontsize}} parameter to the {{ic|1=netbeans_default_options}} property.[https://web.archive.org/web/20210117211145/http://wiki.netbeans.org/FaqFontSize]<br />
<br />
The editor fontsize can be controlled from ''Tools > Option > Fonts & Colors''.<br />
<br />
The output window fontsize can be controlled from ''Tools > Options > Miscelaneous > Output''<br />
<br />
=== OBS Studio ===<br />
<br />
Start obs with the environment variable {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} to disable [https://doc.qt.io/qt-5/highdpi.html#migrate-existing-applications Qt’s hi-dpi migration mode]. It is partially buggy (preview window can disappear after first start, depending on window position) and prevents OBS Studio from capturing at native resolution.<br />
<br />
The downside of this option is that the UI elements will now be messed up. To mitigate this, install the Yami theme, which works well on hi-dpi displays:<br />
<br />
{{Accuracy|Installation from archive other than the source of the {{Pkg|obs-studio}} package is not supported.}}<br />
<br />
$ wget https://github.com/obsproject/obs-studio/archive/fd256a46837033b9a4632327ece3c572bcb3b9b1.tar.gz -O /tmp/yami.tar.gz<br />
$ cd ~/.config/obs-studio<br />
$ tar xf /tmp/yami.tar.gz --strip-components=3 --wildcards '*/UI/data/themes/Yami*'<br />
<br />
Then, open File → Settings → General → Theme and chose Yami.<br />
<br />
=== Skype ===<br />
<br />
Skype for Linux ({{AUR|skypeforlinux-stable-bin}} package) uses [[#GDK 3 (GTK 3)]].<br />
<br />
=== Spotify ===<br />
<br />
You can change scale factor by simple {{ic|Ctrl++}} for zoom in, {{ic|Ctrl+-}} for zoom out and {{ic|Ctrl+0}} for default scale. Scaling setting will be saved in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, you may have to create this file by yourself:<br />
<br />
{{hc|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs|2=<br />
app.browser.zoom-level=100<br />
}}<br />
<br />
Also Spotify can be launched with a custom scaling factor which will be multiplied with setting specified in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, for example<br />
<br />
$ spotify --force-device-scale-factor=1.5<br />
<br />
=== Steam ===<br />
<br />
==== Official HiDPI support ====<br />
<br />
* Starting on 25 of January 2018 in the beta program there is actual support for HiDPI and it should be automatically detected.<br />
* ''Steam > Settings > Interface'', check "Enlarge text and icons based on monitor size" (restart required)<br />
* If it is not automatically detected, use {{ic|1=GDK_SCALE=2}} to set the desired scale factor.<br />
<br />
==== Unofficial ====<br />
<br />
The [https://github.com/MoriTanosuke/HiDPI-Steam-Skin HiDPI-Steam-Skin] can be installed to increase the font size of the interface. While not perfect, it does improve usability. <br />
<br />
{{Note|The README for the HiDPI skin lists several possible locations for where to place the skin. The correct folder out of these can be identified by the presence of a file named {{ic|1=skins_readme.txt}}.}}<br />
<br />
[https://steamcommunity.com/groups/metroskin/discussions/0/517142253861033946/ MetroSkin Unofficial Patch] also helps with HiDPI on Steam with Linux.<br />
<br />
=== Sublime Text 3 ===<br />
<br />
Sublime Text 3 has full support for display scaling. Go to ''Preferences > Settings > User Settings'' and add {{ic|"ui_scale": 2.0}} to your settings.<br />
<br />
=== Thunderbird ===<br />
<br />
See [[#Firefox]]. To access {{ic|about:config}}, go to ''Edit > Preferences > Advanced >Config editor''.<br />
<br />
=== VirtualBox ===<br />
<br />
{{Note|This only applies to KDE with scaling enabled.}}<br />
<br />
VirtualBox also applies the system-wide scaling to the virtual monitor, which reduces the maximum resolution inside VMs by your scaling factor (see [https://www.virtualbox.org/ticket/16604]).<br />
<br />
This can be worked around by calculating the inverse of your scaling factor and manually setting this new scaling factor for the VirtualBox execution, e.g.<br />
<br />
$ QT_SCALE_FACTOR=0.5 VirtualBox --startvm vm-name<br />
<br />
=== Wine applications ===<br />
<br />
Run<br />
<br />
$ winecfg<br />
<br />
and change the "dpi" setting found in the "Graphics" tab. This only affects the font size.<br />
<br />
=== Zathura document viewer ===<br />
<br />
No modifications required for document viewing.<br />
<br />
UI text scaling is specified via [https://pwmt.org/projects/zathura/documentation/ configuration file] (note that "font" is a [https://pwmt.org/projects/girara/options/ girara option]):<br />
<br />
set font "monospace normal 20"<br />
<br />
=== Zoom ===<br />
<br />
Set the {{ic|scaleFactor}} variable in {{ic|~/.config/zoomus.conf}}.<br />
<br />
For the Flatpak version, set the environment variable {{ic|QT_SCALE_FACTOR}} (e.g. to 0.5 [https://old.reddit.com/r/Zoom/comments/hat5af/linux_client_ui_elements_too_large_after_update/]). This can be easily done with [https://flathub.org/apps/details/com.github.tchx84.Flatseal Flatseal], if using a GUI tool is preferred.<br />
<br />
=== Gazebo ===<br />
<br />
Gazebo only renders an upper left of a view instead of the whole view. To fix this a Qt enviorment variable must be set.<br />
To run Gazebo:<br />
$ QT_SCREEN_SCALE_FACTORS=[1.0] gazebo<br />
To run a ROS simulation:<br />
$ TURTLEBOT3_MODEL=burger QT_SCREEN_SCALE_FACTORS=[1.0] roslaunch turtlebot3_gazebo turtlebot3_world.launch<br />
Making an alias such as gazebo="QT_SCREEN_SCALE_FACTORS=[1.0] gazebo" works for the first case but not for the second.<br />
<br />
=== Fcitx ===<br />
<br />
Fcitx preedit {{ic|FontSize}} can be changed in {{ic|~/.config/fcitx/conf/fcitx-classic-ui.config}}.<br />
<br />
=== Unsupported applications ===<br />
<br />
{{AUR|run_scaled-git}} can be used to scale applications (which uses {{Pkg|xpra}} internally).<br />
<br />
Another approach is to run the application full screen and without decoration in its own VNC desktop. Then scale the viewer. With Vncdesk ({{AUR|vncdesk-git}} from the [[AUR]]) you can set up a desktop per application, then start server and client with a simple command such as {{ic|vncdesk 2}}.<br />
<br />
[[x11vnc]] has an experimental option {{ic|-appshare}}, which opens one viewer per application window. Perhaps something could be hacked up with that.<br />
<br />
== Multiple displays ==<br />
<br />
The HiDPI setting applies to the whole desktop, so non-HiDPI external displays show everything too large. However, note that setting different scaling factors for different monitors is already supported in [[Wayland]].<br />
<br />
=== Side display ===<br />
<br />
One workaround is to use [[xrandr]]'s scale option. To have a non-HiDPI monitor (on DP1) right of an internal HiDPI display (eDP1), one could run:<br />
<br />
$ xrandr --output eDP-1 --auto --output DP-1 --auto --scale 2x2 --right-of eDP-1<br />
<br />
When extending above the internal display, you may see part of the internal display on the external monitor. In that case, specify the position manually.<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
{{Note|1=Above solution with {{ic|--scale 2x2}} does not work on some Nvidia cards. No solution is currently available. [https://bbs.archlinux.org/viewtopic.php?pid=1670840] A potential workaround exists with configuring {{ic|1=ForceFullCompositionPipeline=On}} on the {{ic|CurrentMetaMode}} via {{ic|nvidia-settings}}. For more info see [https://askubuntu.com/a/979551].}}<br />
<br />
{{Note|If you are using the {{ic|modesetting}} driver you will get mouse flickering. This can be solved by scaling your non-scaled screen by 0.9999x0.9999.}}<br />
<br />
=== Multiple external monitors ===<br />
<br />
There might be some problems in scaling more than one external monitors which have lower dpi than the built-in HiDPI display. In that case, you may want to try downscaling the HiDPI display instead, with e.g.<br />
<br />
$ xrandr --output eDP1 --scale 0.5x0.5 --output DP2 --right-of eDP1 --output HDMI1 --right-of DP2<br />
<br />
In addition, when you downscale the HiDPI display, the font on the HiDPI display will be slightly blurry, but it's a different kind of bluriness compared with the one introduced by upscaling the external displays. You may compare and see which kind of bluriness is less problematic for you.<br />
<br />
=== Mirroring ===<br />
<br />
If all you want is to mirror ("unify") displays, this is easy as well:<br />
<br />
With AxB your native HiDPI resolution (for ex 3200x1800) and CxD your external screen resolution (e.g. 1920x1200)<br />
<br />
$ xrandr --output HDMI --scale [A/C]x[B/D]<br />
<br />
In this example which is QHD (3200/1920 = 1.66 and 1800/1200 = 1.5)<br />
<br />
$ xrandr --output HDMI --scale 1.66x1.5<br />
<br />
For UHD to 1080p (3840/1920=2 2160/1080=2)<br />
<br />
$ xrandr --output HDMI --scale 2x2<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
=== Tools ===<br />
<br />
There are several tools which automate the commands described above.<br />
<br />
* [https://gist.github.com/wvengen/178642bbc8236c1bdb67 This script] extend a non-HiDPI external display above a HiDPI internal display.<br />
* [https://github.com/ashwinvis/xrandr-extend xrandr-extend].<br />
* {{AUR|xlayoutdisplay}} is a CLI front end for xrandr which detects and sets correct DPI: [https://github.com/alex-courtis/xlayoutdisplay README]<br />
<br />
== Linux console ==<br />
<br />
The [[w:Linux console|Linux console]] changes the font to {{ic|TER16x32}} (based on {{ic|ter-i32b}} from {{Pkg|terminus-font}}[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ac8b6f148fc97e9e10b48bd337ef571b1d1136aa]) accordingly based on the resolution of the display. If your monitor is not recognised as HiDPI, the default font can be changed. In that case, specify {{ic|1=fbcon=font:TER16x32}} in the [[kernel command line]].<br />
<br />
=== Fonts outside the kernel ===<br />
<br />
The largest fonts present in the {{Pkg|kbd}} package are {{ic|latarcyrheb-sun32}} and {{ic|solar24x32}}. Other packages like {{Pkg|terminus-font}} contain further alternatives, such as {{ic|ter-132n}} (normal) and {{ic|ter-132b}} (bold). See [[Linux console#Fonts]] for configuration details and [[Linux console#Persistent configuration]] in particular for applying the font setting during the early userspace boot sequence.<br />
<br />
After changing the font, it is often garbled and unreadable when changing to other virtual consoles ({{ic|tty2-6}}). To fix this you can [[Kernel_mode_setting#Forcing_modes_and_EDID|force specific mode]] for KMS, such as {{ic|1=video=2560x1600@60}} (substitute in the native resolution of your HiDPI display), and reboot.<br />
<br />
Users booting though [[UEFI]] may experience the console and [[boot loader]] being constrained to a low resolution despite correct [[KMS]] settings being set. This can be caused by legacy/BIOS boot being enabled in UEFI settings. Disabling legacy boot to bypass the compatibility layer should allow the system to boot at the correct resolution.<br />
<br />
== See also ==<br />
<br />
* [https://www.phoronix.com/scan.php?page=article&item=linux_uhd4k_gpus Ultra HD 4K Linux Graphics Card Testing] (Nov 2013)<br />
* [https://www.eizo.com/library/basics/pixel_density_4k/ Understanding pixel density]<br />
* [http://wok.oblomov.eu/tecnologia/mixed-dpi-x11/ Mixed DPI and the X Window System]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Display_manager&diff=705708Display manager2021-12-12T23:24:00Z<p>Thiagowfx: /* List of display managers */ tbsm: unmaintained</p>
<hr />
<div>[[Category:Graphical user interfaces]]<br />
[[Category:Lists of software]]<br />
[[ar:Display manager]]<br />
[[cs:Display manager]]<br />
[[de:Login-Manager]]<br />
[[es:Display manager]]<br />
[[fa:Display manager]]<br />
[[fr:Display manager]]<br />
[[it:Display manager]]<br />
[[ja:ディスプレイマネージャ]]<br />
[[ko:Display manager]]<br />
[[pt:Display manager]]<br />
[[ru:Display manager]]<br />
[[zh-hans:Display manager]]<br />
[[zh-hant:Display manager]]<br />
{{Related articles start}}<br />
{{Related|Start X at login}}<br />
{{Related articles end}}<br />
<br />
A [[Wikipedia:X display manager (program type)|display manager]], or login manager, is typically a graphical user interface that is displayed at the end of the boot process in place of the default shell. There are various implementations of display managers, just as there are various types of [[window managers]] and [[desktop environments]]. There is usually a certain amount of customization and themeability available with each one.<br />
<br />
== List of display managers ==<br />
<br />
=== Console ===<br />
<br />
* {{App|[[CDM]]|Login manager written in Bash.|https://github.com/evertiro/cdm|{{AUR|cdm}}}}<br />
* {{App|[[Console TDM]]|Extension for ''xinit'' written in pure Bash.|https://github.com/dopsi/console-tdm|{{AUR|console-tdm}}}}<br />
* {{App|[[nodm]]|Display manager for automatic logins (unmaintained since 2017).|https://github.com/spanezz/nodm|{{Pkg|nodm}}}}<br />
* {{App|Ly|TUI (ncurses-like) display manager for Linux and BSD. Supports X and Wayland sessions.|https://github.com/nullgemm/ly|{{AUR|ly}}}}<br />
* {{App|tbsm|A Bash session or application launcher. Supports X and Wayland sessions (unmaintained since 2018).|https://loh-tar.github.io/tbsm/|{{AUR|tbsm}}}}<br />
* {{App|emptty|Simple CLI Display Manager on TTY with X and Wayland support.|https://github.com/tvrzna/emptty/|{{AUR|emptty-git}}}}<br />
<br />
=== Graphical ===<br />
<br />
* {{App|[[Entrance]]|[[Enlightenment]] display manager.|https://github.com/Obsidian-StudiosInc/entrance|{{AUR|entrance-git}}}}<br />
* {{App|[[GDM]]|[[GNOME]] display manager.|https://wiki.gnome.org/Projects/GDM|{{Pkg|gdm}}}}<br />
* {{App|[[LightDM]]|Cross-desktop display manager, can use various front-ends written in any toolkit.|https://github.com/CanonicalLtd/lightdm/|{{Pkg|lightdm}}}}<br />
* {{App|[[LXDM]]|[[LXDE]] display manager. Can be used independent of the LXDE desktop environment.|https://sourceforge.net/projects/lxdm/|{{Pkg|lxdm}}}}<br />
* {{App|[[SDDM]]|QML-based display manager and successor to KDM; recommended for [[Plasma]] and [[LXQt]].|https://github.com/sddm/sddm|{{Pkg|sddm}}}}<br />
* {{App|[[XDM]]|X display manager with support for XDMCP, host chooser.|{{man|8|xdm}}|{{Pkg|xorg-xdm}}}}<br />
<br />
=== Login daemons ===<br />
<br />
* {{App|[[greetd]]|Login daemon which supports both console and graphical greeters.|https://git.sr.ht/~kennylevinsen/greetd|{{AUR|greetd}}}}<br />
<br />
== Loading the display manager ==<br />
<br />
To enable graphical login, [[enable]] the appropriate systemd service. For example, for [[SDDM]], enable {{ic|sddm.service}}.<br />
<br />
This should work out of the box. If not, you might have to reset a custom {{ic|default.target}} symlink to point to the default {{ic|graphical.target}}. See [[systemd#Change default target to boot into]].<br />
<br />
After enabling [[SDDM]] a symlink {{ic|display-manager.service}} should be set in {{ic|/etc/systemd/system/}}. You may need to use {{ic|--force}} to override old symlinks.<br />
<br />
{{hc|$ file /etc/systemd/system/display-manager.service|<br />
/etc/systemd/system/display-manager.service: symbolic link to /usr/lib/systemd/system/sddm.service<br />
}}<br />
<br />
=== Using systemd-logind ===<br />
<br />
In order to check the status of your user session, you can use ''loginctl''. All [[polkit]] actions like suspending the system or mounting external drives will work out of the box.<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
== Session configuration ==<br />
<br />
Many display managers read available sessions from {{ic|/usr/share/xsessions/}} directory. It contains standard [https://specifications.freedesktop.org/desktop-entry-spec/latest/ desktop entry files] for each desktop environment or window manager. Some display managers use a separate {{ic|/usr/share/wayland-sessions/}} to list [[Wayland]]-specific sessions.<br />
<br />
To add/remove entries to your display manager's session list; create/remove the ''.desktop'' files in {{ic|/usr/share/xsessions/}} as desired. A typical ''.desktop'' file will look something like:<br />
<br />
[Desktop Entry]<br />
Name=Openbox<br />
Comment=Log in using the Openbox window manager (without a session manager)<br />
Exec=/usr/bin/openbox-session<br />
TryExec=/usr/bin/openbox-session<br />
Icon=openbox.png<br />
Type=Application<br />
<br />
=== Run ~/.xinitrc as a session ===<br />
<br />
Installing {{AUR|xinit-xsession}} will provide an option to run your [[xinitrc]] as a session. Simply set {{ic|xinitrc}} as the session in your display manager's settings and make sure that the {{ic|~/.xinitrc}} file is executable.<br />
<br />
=== Starting applications without a window manager ===<br />
<br />
You can also launch an application without any decoration, desktop, or window management. For example to launch {{AUR|google-chrome}} create a {{ic|web-browser.desktop}} file in {{ic|/usr/share/xsessions/}} like this:<br />
<br />
[Desktop Entry]<br />
Name=Web Browser<br />
Comment=Use a web browser as your session<br />
Exec=/usr/bin/google-chrome --auto-launch-at-startup<br />
TryExec=/usr/bin/google-chrome --auto-launch-at-startup<br />
Icon=google-chrome<br />
Type=Application<br />
<br />
In this case, once you login, the application set with {{ic|Exec}} will be launched immediately. When you close the application, you will be taken back to the login manager (same as logging out of a normal desktop environment or window manager).<br />
<br />
It is important to remember that most graphical applications are not intended to be launched this way and you might have manual tweaking to do or limitations to live with (there is no window manager, so do not expect to be able to move or resize ''any'' windows, including dialogs; nonetheless, you might be able to set the window geometry in the application's configuration files).<br />
<br />
See also [[xinitrc#Starting applications without a window manager]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Autostarting ===<br />
<br />
Most display managers source {{ic|/etc/xprofile}}, {{ic|~/.xprofile}} and {{ic|/etc/X11/xinit/xinitrc.d/}}. For more details, see [[xprofile]].<br />
<br />
=== Set language for user session ===<br />
<br />
For display managers that use [https://freedesktop.org/wiki/Software/AccountsService/ AccountsService] the [[locale]] for the user session can be set by editing:{{hc|/var/lib/AccountsService/users/$USER|2=<br />
[User]<br />
Language=''your_locale''}}<br />
<br />
where ''your_locale'' is a value such as {{ic|en_GB.UTF-8}}.<br />
<br />
Alternatively, you can achieve this using [[D-Bus]]:<br />
{{ic|busctl call org.freedesktop.Accounts /org/freedesktop/Accounts/User$UID org.freedesktop.Accounts.User SetLanguage s ''your_locale''}}<br />
<br />
Log out and then back in again for the changes to take effect.</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Display_manager&diff=705707Display manager2021-12-12T23:22:22Z<p>Thiagowfx: /* List of display managers */ ly: add note: Supports X and Wayland sessions.</p>
<hr />
<div>[[Category:Graphical user interfaces]]<br />
[[Category:Lists of software]]<br />
[[ar:Display manager]]<br />
[[cs:Display manager]]<br />
[[de:Login-Manager]]<br />
[[es:Display manager]]<br />
[[fa:Display manager]]<br />
[[fr:Display manager]]<br />
[[it:Display manager]]<br />
[[ja:ディスプレイマネージャ]]<br />
[[ko:Display manager]]<br />
[[pt:Display manager]]<br />
[[ru:Display manager]]<br />
[[zh-hans:Display manager]]<br />
[[zh-hant:Display manager]]<br />
{{Related articles start}}<br />
{{Related|Start X at login}}<br />
{{Related articles end}}<br />
<br />
A [[Wikipedia:X display manager (program type)|display manager]], or login manager, is typically a graphical user interface that is displayed at the end of the boot process in place of the default shell. There are various implementations of display managers, just as there are various types of [[window managers]] and [[desktop environments]]. There is usually a certain amount of customization and themeability available with each one.<br />
<br />
== List of display managers ==<br />
<br />
=== Console ===<br />
<br />
* {{App|[[CDM]]|Login manager written in Bash.|https://github.com/evertiro/cdm|{{AUR|cdm}}}}<br />
* {{App|[[Console TDM]]|Extension for ''xinit'' written in pure Bash.|https://github.com/dopsi/console-tdm|{{AUR|console-tdm}}}}<br />
* {{App|[[nodm]]|Display manager for automatic logins (unmaintained since 2017).|https://github.com/spanezz/nodm|{{Pkg|nodm}}}}<br />
* {{App|Ly|TUI (ncurses-like) display manager for Linux and BSD. Supports X and Wayland sessions.|https://github.com/nullgemm/ly|{{AUR|ly}}}}<br />
* {{App|tbsm|A Bash session or application launcher. Supports X and Wayland sessions.|https://loh-tar.github.io/tbsm/|{{AUR|tbsm}}}}<br />
* {{App|emptty|Simple CLI Display Manager on TTY with X and Wayland support.|https://github.com/tvrzna/emptty/|{{AUR|emptty-git}}}}<br />
<br />
=== Graphical ===<br />
<br />
* {{App|[[Entrance]]|[[Enlightenment]] display manager.|https://github.com/Obsidian-StudiosInc/entrance|{{AUR|entrance-git}}}}<br />
* {{App|[[GDM]]|[[GNOME]] display manager.|https://wiki.gnome.org/Projects/GDM|{{Pkg|gdm}}}}<br />
* {{App|[[LightDM]]|Cross-desktop display manager, can use various front-ends written in any toolkit.|https://github.com/CanonicalLtd/lightdm/|{{Pkg|lightdm}}}}<br />
* {{App|[[LXDM]]|[[LXDE]] display manager. Can be used independent of the LXDE desktop environment.|https://sourceforge.net/projects/lxdm/|{{Pkg|lxdm}}}}<br />
* {{App|[[SDDM]]|QML-based display manager and successor to KDM; recommended for [[Plasma]] and [[LXQt]].|https://github.com/sddm/sddm|{{Pkg|sddm}}}}<br />
* {{App|[[XDM]]|X display manager with support for XDMCP, host chooser.|{{man|8|xdm}}|{{Pkg|xorg-xdm}}}}<br />
<br />
=== Login daemons ===<br />
<br />
* {{App|[[greetd]]|Login daemon which supports both console and graphical greeters.|https://git.sr.ht/~kennylevinsen/greetd|{{AUR|greetd}}}}<br />
<br />
== Loading the display manager ==<br />
<br />
To enable graphical login, [[enable]] the appropriate systemd service. For example, for [[SDDM]], enable {{ic|sddm.service}}.<br />
<br />
This should work out of the box. If not, you might have to reset a custom {{ic|default.target}} symlink to point to the default {{ic|graphical.target}}. See [[systemd#Change default target to boot into]].<br />
<br />
After enabling [[SDDM]] a symlink {{ic|display-manager.service}} should be set in {{ic|/etc/systemd/system/}}. You may need to use {{ic|--force}} to override old symlinks.<br />
<br />
{{hc|$ file /etc/systemd/system/display-manager.service|<br />
/etc/systemd/system/display-manager.service: symbolic link to /usr/lib/systemd/system/sddm.service<br />
}}<br />
<br />
=== Using systemd-logind ===<br />
<br />
In order to check the status of your user session, you can use ''loginctl''. All [[polkit]] actions like suspending the system or mounting external drives will work out of the box.<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
== Session configuration ==<br />
<br />
Many display managers read available sessions from {{ic|/usr/share/xsessions/}} directory. It contains standard [https://specifications.freedesktop.org/desktop-entry-spec/latest/ desktop entry files] for each desktop environment or window manager. Some display managers use a separate {{ic|/usr/share/wayland-sessions/}} to list [[Wayland]]-specific sessions.<br />
<br />
To add/remove entries to your display manager's session list; create/remove the ''.desktop'' files in {{ic|/usr/share/xsessions/}} as desired. A typical ''.desktop'' file will look something like:<br />
<br />
[Desktop Entry]<br />
Name=Openbox<br />
Comment=Log in using the Openbox window manager (without a session manager)<br />
Exec=/usr/bin/openbox-session<br />
TryExec=/usr/bin/openbox-session<br />
Icon=openbox.png<br />
Type=Application<br />
<br />
=== Run ~/.xinitrc as a session ===<br />
<br />
Installing {{AUR|xinit-xsession}} will provide an option to run your [[xinitrc]] as a session. Simply set {{ic|xinitrc}} as the session in your display manager's settings and make sure that the {{ic|~/.xinitrc}} file is executable.<br />
<br />
=== Starting applications without a window manager ===<br />
<br />
You can also launch an application without any decoration, desktop, or window management. For example to launch {{AUR|google-chrome}} create a {{ic|web-browser.desktop}} file in {{ic|/usr/share/xsessions/}} like this:<br />
<br />
[Desktop Entry]<br />
Name=Web Browser<br />
Comment=Use a web browser as your session<br />
Exec=/usr/bin/google-chrome --auto-launch-at-startup<br />
TryExec=/usr/bin/google-chrome --auto-launch-at-startup<br />
Icon=google-chrome<br />
Type=Application<br />
<br />
In this case, once you login, the application set with {{ic|Exec}} will be launched immediately. When you close the application, you will be taken back to the login manager (same as logging out of a normal desktop environment or window manager).<br />
<br />
It is important to remember that most graphical applications are not intended to be launched this way and you might have manual tweaking to do or limitations to live with (there is no window manager, so do not expect to be able to move or resize ''any'' windows, including dialogs; nonetheless, you might be able to set the window geometry in the application's configuration files).<br />
<br />
See also [[xinitrc#Starting applications without a window manager]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Autostarting ===<br />
<br />
Most display managers source {{ic|/etc/xprofile}}, {{ic|~/.xprofile}} and {{ic|/etc/X11/xinit/xinitrc.d/}}. For more details, see [[xprofile]].<br />
<br />
=== Set language for user session ===<br />
<br />
For display managers that use [https://freedesktop.org/wiki/Software/AccountsService/ AccountsService] the [[locale]] for the user session can be set by editing:{{hc|/var/lib/AccountsService/users/$USER|2=<br />
[User]<br />
Language=''your_locale''}}<br />
<br />
where ''your_locale'' is a value such as {{ic|en_GB.UTF-8}}.<br />
<br />
Alternatively, you can achieve this using [[D-Bus]]:<br />
{{ic|busctl call org.freedesktop.Accounts /org/freedesktop/Accounts/User$UID org.freedesktop.Accounts.User SetLanguage s ''your_locale''}}<br />
<br />
Log out and then back in again for the changes to take effect.</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Apple_Keyboard&diff=699736Apple Keyboard2021-10-22T18:45:41Z<p>Thiagowfx: /* No input during root disk decryption */ ic formatting</p>
<hr />
<div>[[Category:Keyboards]]<br />
[[ja:Apple Keyboard]]<br />
{{Related articles start}}<br />
{{Related|Extra keyboard keys}}<br />
{{Related articles end}}<br />
<br />
Some keyboard models that use the Apple keyboard driver may have swapped keys or missing functionality. This article describes how to change the settings for the keyboard so that it behaves as expected.<br />
<br />
== Numlock is on ==<br />
<br />
You may find that the numlock is on. The symptoms are that only the physical keys {{ic|7}},{{ic|8}},{{ic|9}},{{ic|u}},{{ic|i}},{{ic|o}},{{ic|j}},{{ic|k}},{{ic|l}} and surrounding keys work and output numbers. To fix this hit {{ic|Fn+F6}} twice. You might need to use a utility like {{Pkg|numlockx}}.<br />
<br />
Alternatively, set the keycodes manually using [[xmodmap]] to avoid use Numlock:<br />
<br />
keycode 90 = KP_0 KP_0 KP_0 KP_0 KP_0 KP_0<br />
keycode 87 = KP_1 KP_1 KP_1 KP_1 KP_1 KP_1<br />
keycode 88 = KP_2 KP_2 KP_2 KP_2 KP_2 KP_2<br />
keycode 89 = KP_3 KP_3 KP_3 KP_3 KP_3 KP_3<br />
keycode 83 = KP_4 KP_4 KP_4 KP_4 KP_4 KP_4<br />
keycode 84 = KP_5 KP_5 KP_5 KP_5 KP_5 KP_5<br />
keycode 85 = KP_6 KP_6 KP_6 KP_6 KP_6 KP_6<br />
keycode 79 = KP_7 KP_7 KP_7 KP_7 KP_7 KP_7<br />
keycode 80 = KP_8 KP_8 KP_8 KP_8 KP_8 KP_8<br />
keycode 81 = KP_9 KP_9 KP_9 KP_9 KP_9 KP_9<br />
<br />
== Repeating keys on a wireless keyboard ==<br />
<br />
Unpair the keyboard and then re-pair it. The trick is to hold down the power button throughout the entire pairing process.<br />
<br />
== hid_apple module options ==<br />
<br />
* fnmode - Mode of top-row keys<br />
<br />
0 = disabled<br />
1 = normally media keys, switchable to function keys by holding Fn key (Default)<br />
2 = normally function keys, switchable to media keys by holding Fn key<br />
* swap_opt_cmd - Swap the Option ("Alt") and Command ("Flag") keys<br />
<br />
0 = as silkscreened, Mac layout (Default)<br />
1 = swapped, PC layout<br />
<br />
* iso_layout - Enable/Disable hardcoded ISO-layout of the keyboard. Possibly relevant for international keyboard layouts<br />
<br />
0 = disabled,<br />
1 = enabled (Default)<br />
<br />
* swap_fn_leftctrl - Swap the Fn and left Control keys<br />
<br />
0 = as silkscreened, Mac layout (Default)<br />
1 = swapped, PC layout<br />
<br />
== Function keys do not work ==<br />
<br />
If your {{ic|F<num>}} keys do not work, this is probably because the kernel driver for the keyboard has defaulted to using the media keys and requiring you to use the {{ic|Fn}} key to get to the {{ic|F<num>}} keys. To change the behavior temporarily, [[append]] {{ic|2}} to {{ic|/sys/module/hid_apple/parameters/fnmode}}.<br />
<br />
# echo 2 >> /sys/module/hid_apple/parameters/fnmode<br />
<br />
To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|fnmode}} option to 2:<br />
<br />
{{hc|/etc/modprobe.d/hid_apple.conf|2=<br />
options hid_apple fnmode=2<br />
}}<br />
<br />
To apply the change to your initial ramdisk, in your [[Mkinitcpio#Configuration|mkinitcpio configuration]] (usually {{ic|/etc/mkinitcpio.conf}}), make sure you either have {{ic|modconf}} included in the {{ic|HOOKS}} variable or {{ic|/etc/modprobe.d/hid_apple.conf}} in the {{ic|FILES}} variable. You would then need to [[regenerate the initramfs]].<br />
<br />
== Switching Cmd and Alt/AltGr ==<br />
<br />
This will switch the left {{ic|Alt}} and {{ic|Cmd}} key as well as the right {{ic|Alt}}/{{ic|AltGr}} and {{ic|Cmd}} key.<br />
<br />
Temporary and immediate solution:<br />
<br />
# echo "1" > /sys/module/hid_apple/parameters/swap_opt_cmd<br />
<br />
Permanent change, taking place at next reboot:<br />
<br />
{{hc|/etc/modprobe.d/hid_apple.conf|2=<br />
options hid_apple swap_opt_cmd=1<br />
}}<br />
<br />
You then need to [[regenerate the initramfs]].<br />
<br />
== Swap the Fn and left Control keys ==<br />
<br />
This will switch the {{ic|Fn}} and left {{ic|Control}} keys.<br />
<br />
Temporary and immediate solution:<br />
<br />
# echo "1" > /sys/module/hid_apple/parameters/swap_fn_leftctrl<br />
<br />
Permanent change, taking place at next reboot:<br />
<br />
{{hc|/etc/modprobe.d/hid_apple.conf|2=<br />
options hid_apple swap_fn_leftctrl=1<br />
}}<br />
<br />
You then need to [[regenerate the initramfs]].<br />
<br />
== < and > have changed place with § and ½ ==<br />
<br />
{{Remove|This issue is only present in very old kernels (< 2.6.19) and the apple:badmap directive was removed years ago|section=Removal of section about apple:badmap}}<br />
<br />
If the '''<''' and '''>''' are switched with the '''§''' and '''½''' keys, [[Keyboard_configuration_in_Xorg|set the xkb option]] {{ic|apple:badmap}}, for instance by running the following command in your graphical environment:<br />
<br />
$ setxkbmap -option apple:badmap<br />
<br />
Alternatively, set the keycodes manually using [[xmodmap]]:<br />
<br />
keycode 49 = less greater less greater bar brokenbar<br />
keycode 94 = section degree section degree notsign notsign<br />
<br />
If you use a Canadian multilingual layout (where the "ù" and the "/" is switch) use this:<br />
<br />
keycode 94 = slash backslash slash backslash bar brokenbar<br />
keycode 49 = ugrave Ugrave ugrave Ugrave notsign notsign<br />
<br />
== < and > have changed place with ^ and ° (or @ and #, or ` and ~) ==<br />
<br />
With German layout, circumflex/degree symbol and </> are exchanged. With French layout, @/# are exchanged. With the US layout, `/~ and </> are exchanged.<br />
<br />
To change the behavior temporarily, [[Help:Reading#Append, add, create, edit|overwrite]] {{ic|/sys/module/hid_apple/parameters/iso_layout}} with {{ic|0}}:<br />
<br />
# echo "0" > /sys/module/hid_apple/parameters/iso_layout<br />
<br />
To make the change permanent, [[Kernel_modules#Setting_module_options|set]] the {{ic|hid_apple}} {{ic|iso_layout}} option to 0:<br />
<br />
{{hc|/etc/modprobe.d/hid_apple.conf|2=<br />
options hid_apple iso_layout=0<br />
}}<br />
<br />
You then need to [[regenerate the initramfs]].<br />
<br />
== PrintScreen and SysRq ==<br />
<br />
Apple Keyboards have an {{ic|F13}} key instead of a {{ic|PrintScreen}}/{{ic|SysRq}} key. This means that [[Keyboard shortcuts#Kernel (SysRq)|Alt+SysRq sequences]] do not work, and application actions associated with {{ic|PrintScreen}} (such as taking screenshots in many games that work under [[Wine]]) do not work. To fix this, you can add {{ic|setxkbmap -option "apple:alupckeys"}} to your {{ic|.xinitrc}}. This will map {{ic|PrintScreen}}/{{ic|SysRq}} to {{ic|F13}}, as well as {{ic|Scroll lock}} to {{ic|F14}} and {{ic|Pause}} to {{ic|F15}}.<br />
<br />
Alternatively, follow the [[Map scancodes to keycodes]] article to map the {{ic|F13}} scancode to the {{ic|PrintScreen}}/{{ic|SysRq}} keycode, where 458856 (0x0'''70068''') is the scancode of {{ic|F13}}, and {{ic|sysrq}} is the keycode of {{ic|PrintScreen}}/{{ic|SysRq}}.<br />
<br />
== Treating Apple keyboards like regular keyboards ==<br />
<br />
Depending on the customisations you want to accomplish, there are two solutions available and some options that are in the kernel. You need to choose one of the other.<br />
<br />
=== Use a patch to hid-apple ===<br />
<br />
While the original {{ic|hid-apple}} module does not have options to further customize the keyboard, like swapping {{ic|Fn}} and left {{ic|Ctrl}} keys or having {{ic|Alt}} on the left side of {{ic|Super}}, there is a [https://github.com/free5lot/hid-apple-patched patched version] adding this functionality to the module. To use it, [[install]] the {{AUR|hid-apple-patched-git-dkms}} package. This will install the patched {{ic|hid-apple}} and mask out the original one.<br />
<br />
The package uses [[DKMS]] to automatically recompile the module during kernel upgrades. While the {{Pkg|dkms}} will be pulled in by dependency. You still need to install an appropriate kernel header package manually. See the DKMS page for more info.<br />
<br />
In addition to the patched kernel module, a configuration file is also provided by the package at {{ic|/usr/lib/modprobe.d/hid_apple.conf}}, which enables PC-like layout by default:<br />
<br />
* Top-row keys are normally function keys, switchable to media keys by holding Fn key, as in [[#Function keys do not work]].<br />
* Four keys at the lower left corner act as {{ic|Ctrl}}, {{ic|Fn}}, {{ic|Super}}, {{ic|Alt}}, in this order.<br />
* Two keys at the lower right corner act as {{ic|Alt}}, {{ic|Ctrl}}, in this order.<br />
* If you have an {{ic|Ejectcd}} key, it will act as {{ic|Delete}} key.<br />
<br />
If you wish to change the default options, copy the configuration file to {{ic|/etc/modprobe.d}} and make desired changes:<br />
<br />
sudo cp {/usr/lib,/etc}/modprobe.d/hid_apple.conf<br />
<br />
The file under {{ic|/etc/modprobe.d}} will completely override the one with the same name under {{ic|/usr/lib/modprobe.d}}, and the content is '''NOT''' merged.<br />
<br />
Alternatively, put additional options in a file with a different name if you want to keep default ones, <br />
<br />
{{Note|Do not forget to update ''initramfs'' after manual changes to configuration files.}}<br />
<br />
Please refer to the project [https://github.com/free5lot/hid-apple-patched#configuration README] for the exact meaning of each configuration option and tweaking the configuration file to suit your needs. Learn more about {{ic|modprobe.d}} at [[Kernel module#Using files in /etc/modprobe.d/]].<br />
<br />
After installation, reboot for the change to take effect, or [[#Change the Behavior Without Reboot]].<br />
<br />
==== Troubleshooting configuration not picked up by the module ====<br />
<br />
First, make sure the patched version is loaded, see what parameters are provided by the module:<br />
<br />
ls /sys/module/hid_apple/parameters/<br />
<br />
If you do not see new options like {{ic|swap_fn_leftctrl}}, {{ic|ejectcd_as_delete}}, etc., check your dkms installation.<br />
<br />
Then, check if configuration files are correctly included in ''initramfs'':<br />
<br />
mkdir inintramfs && lsinitcpio -x /boot/initramfs-linux.img<br />
<br />
Check the presence and content of {{ic|inintramfs/usr/lib/modprobe.d/hid_apple.conf}} and any other relevant configuration files in {{ic|inintramfs/etc/modprobe.d}}. If they are not there, you should check your {{ic|/etc/mkinitcpio.conf}} to include those. By default, there should<br />
be a {{ic|modconf}} hook that automatically include those files, if not, add it to the {{ic|HOOKS}} array after {{ic|autodetect}}.<br />
<br />
Alternatively, list those files in {{ic|FILES}} array explicitly:<br />
<br />
FILES=(/usr/lib/modprobe.d/hid_apple.conf)<br />
<br />
Refer to [[Mkinitcpio#BINARIES and FILES]] and [[Mkinitcpio#HOOKS]] for more explanation on what this means.<br />
<br />
Finally, rebuild the ''initramfs'' and reboot.<br />
<br />
sudo mkinitcpio -P<br />
<br />
=== Use un-apple-keyboard ===<br />
<br />
If you do not need all of these customizations and you do not want to compile a new module manually or using dkms, there is an AUR package {{AUR|un-apple-keyboard}} which does not rely on a new kernel module, but rather just to mappings. It enables the following features:<br />
<br />
* The keyboard is considered as an ISO keyboard (e.g. {{ic|<}} and {{ic|>}} located at the right of the {{ic|Left Shift}} key are working like expected).<br />
* The function keys are disabled by default. You need to press the {{ic|Fn}} key in combination to trigger them. By default, the behavior are thus keys {{ic|F1}} to {{ic|F12}}<br />
* The {{ic|Alt}} and {{ic|Cmd}} keys are swapped.<br />
* {{ic|F13}} is mapped to {{ic|SYSRQ}}, {{ic|F14}} to {{ic|Scroll Lock}} and {{ic|F15}} to {{ic|Pause}}.<br />
<br />
The first 3 aforementioned features are brought to you using the default linux kernel module {{ic|hid-apple}}.<br />
<br />
The last one is provided by providing a mapping to {{AUR|keyfuzz}}.<br />
<br />
=== Change the Behavior Without Reboot ===<br />
<br />
{{Warning|If the builtin keyboard and touch pad are the only input device, beware that doing so might leave your computer in an inoperable state unless hard reboot when the second command failes.}}<br />
<br />
To reload the kernel module without reboot, run {{ic|rmmod hid_apple && modprobe hid_apple}}.<br />
<br />
== Magic Keyboard does not connect ==<br />
<br />
If you have a magic keyboard that will not connect to the system through the built in tools, such as the Gnome 3 bluetooth menu in settings, install {{Pkg|blueman}} and its dependencies and attempt to connect with it. If it still fails to connect, make sure you have bluetoothctl and hcitool installed.<br />
<br />
== Enable dvorak/dvp ==<br />
<br />
By default xkb loads translation table (actually called {{ic|xkb_symbols}}) {{ic|macintosh_vndr/us}} for macintosh keyboard:<br />
<br />
setxkbmap -print -verbose 10 | grep symbols<br />
<br />
This translation table located in {{ic|/usr/share/X11/xkb/symbols/macintosh_vndr/us}} and do not contains dvorak/dvp layout. You can use default translation table from {{ic|/usr/share/X11/xkb/symbols/us}} and add command {{ic|setxkbmap}} in your {{ic|.profile}} for forced loading layout:<br />
<br />
sudo mv /usr/share/X11/xkb/symbols/macintosh_vndr/us /usr/share/X11/xkb/symbols/macintosh_vndr/us.back<br />
sudo cp /usr/share/X11/xkb/symbols/us /usr/share/X11/xkb/symbols/macintosh_vndr/us<br />
echo "setxkbmap -v 10 -layout us -variant dvp" >> .xprofile<br />
<br />
== No input during root disk decryption ==<br />
<br />
You may have to manually add the {{ic|hid_apple}} module to the [[Mkinitcpio#Configuration|mkinitcpio configuration]]:<br />
<br />
MODULES="hid_apple"<br />
<br />
Or place the keyboard hook before autodetect so that all keyboard drivers are included:<br />
<br />
HOOKS="... keyboard autodetect ..."<br />
<br />
[[Regenerate the initramfs]] after doing either of these.<br />
<br />
== See also ==<br />
<br />
* https://help.ubuntu.com/community/AppleKeyboard<br />
* https://github.com/hlechner/xmodmap-aluminium-pt-br<br />
* https://github.com/free5lot/hid-apple-patched</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=I3&diff=693322I32021-08-29T05:31:13Z<p>Thiagowfx: remove j4-make-config, it's abandonware at this point (inactive since beginning of 2018, no commits and no reply to issues/PRs)</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Tiling window managers]]<br />
[[Category:Dynamic window managers]]<br />
[[de:i3]]<br />
[[es:I3]]<br />
[[fr:I3]]<br />
[[hu:I3]]<br />
[[ja:i3]]<br />
[[ko:I3]]<br />
[[pt:I3]]<br />
[[ru:I3]]<br />
[[zh-hans:I3]]<br />
{{Related articles start}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Window manager}}<br />
{{Related articles end}}<br />
[https://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 />
''i3'' can be installed with the {{Pkg|i3-wm}} package.<br />
<br />
An {{Grp|i3}} package group is also available. It includes the window manager, a screen locker and two programs which write a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]].<br />
<br />
{{Note|{{Pkg|i3-wm}} conflicts with {{Pkg|i3-gaps}} (a fork of ''i3'' with gaps and other features) and by default {{Pkg|i3-gaps}} will be installed.}}<br />
<br />
== Starting ==<br />
<br />
=== From tty ===<br />
<br />
Run {{ic|i3}} with [[xinit]].<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 ''i3'' into [[GNOME]].<br />
<br />
== Usage ==<br />
<br />
See the [https://i3wm.org/docs official documentation] for more information, namely the [https://i3wm.org/docs/userguide.html i3 User's Guide].<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 [https://i3wm.org/docs/refcard.html i3 reference card] and [https://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [https://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.<br />
<br />
Users of non-Qwerty keyboard layouts may wish to circumvent the "configuration wizard" as [[#Configuration wizard and alternative keyboard layouts|described below]].<br />
<br />
If switching between multiple window managers or desktop environments, consider using [[sxhkd]] or another environment agnostic program to manage bindings. More information can be found in [[Keyboard shortcuts#Xorg]].<br />
<br />
=== Containers and layouts ===<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 [https://i3wm.org/docs/userguide.html#_layout_mode_for_new_containers tabbed or stacking] layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.<br />
<br />
See [https://i3wm.org/docs/userguide.html#_tree i3 Tree] and [https://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.<br />
<br />
=== Application launcher ===<br />
<br />
''i3'' uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}. As it is an optional dependency {{Pkg|dmenu}} must first be installed before this functionality can be used.<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.<br />
<br />
[[Rofi#Rofi_as_dmenu_replacement|rofi]] is a popular ''dmenu'' replacement and more that can list desktop entries.<br />
<br />
==== KRunner as application launcher in KDE Plasma/i3 ====<br />
<br />
It is possible to have i3 running alongside KDE Plasma as seen here: [[KDE#Use a different window manager]]<br />
<br />
When running Plasma with {{ic|1=KDEWM=/usr/bin/i3}}, one can set [[KRunner]] as alternative application launcher with {{ic|$mod+d}} by adding the following to the ''i3'' config:<br />
<br />
{{hc|~/.config/i3/config|2=<br />
set $menu --no-startup-id qdbus org.kde.krunner /App display<br />
bindsym $mod+d exec $menu<br />
}}<br />
<br />
== Configuration ==<br />
<br />
See [https://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/}}.<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|~/.config/i3/config}} by rewriting a template configuration file in {{ic|/etc/i3/config.keycodes}}. It makes two 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 />
Step 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 in ways which break the mnemonics - 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 straightforward key bindings, which match the bindings given in tutorials, may prefer to circumvent the "config wizard". This can be done by just copying {{ic|/etc/i3/config}} into {{ic|~/.config/i3/config}} (or {{ic|~/.i3/config}}), and editing that file.<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 />
=== Autostart ===<br />
<br />
Add an {{ic|exec}} command in {{ic|~/.config/i3/config}} file. For example:<br />
<br />
exec terminator<br />
<br />
Alternatively, you can use [[XDG Autostart]].<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 [https://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.<br />
<br />
==== i3bar alternatives ====<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 example, to use the [[Xfce]] panel ({{Pkg|xfce4-panel}}), add the following line anywhere in {{ic|~/.config/i3/config}}:<br />
<br />
exec --no-startup-id xfce4-panel --disable-wm-check<br />
<br />
i3bar can be disabled by commenting the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}}, or defining a keybind to toggle the bar:<br />
<br />
{{hc|~/.config/i3/config|<br />
# bar toggle, hide or show <br />
bindsym $mod+m bar mode toggle<br />
}}<br />
<br />
Replacements independent of the desktop environment are listed below:<br />
* {{App|[[polybar]]|A fast and easy-to-use tool for creating status bars.|https://github.com/jaagr/polybar|{{AUR|polybar}}}}<br />
* {{App|excalibar|Lightweight yet customizable status bar written in C.|https://github.com/cylgom/excalibar|{{AUR|excalibar-git}}}}<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 they need to be updated accordingly. See {{man|1|i3status}} for details.<br />
<br />
==== i3status replacements ====<br />
<br />
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [https://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|{{Pkg|i3blocks}}, {{AUR|i3blocks-git}} }}<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|j4status|Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by {{AUR|j4status-plugins-git}}.|https://sardemff7.github.io/j4status/|{{AUR|j4status-git}}}}<br />
* {{App|goi3bar|i3status replacement written in Go. Configuration-file driven with several plugins, concurrency options, and rich plugin support.|https://github.com/denbeigh2000/goi3bar/|{{AUR|goi3bar-git}}}}<br />
* {{App|goblocks|Fast, lightweight i3status replacement written in Go.|https://github.com/davidscholberg/goblocks|{{AUR|goblocks}}}}<br />
* {{App|bumblebee-status|Theme-able Python status bar generator.|https://github.com/tobi-wan-kenobi/bumblebee-status|{{AUR|bumblebee-status}} {{AUR|bumblebee-status-git}}}}<br />
* {{App|ty3status|i3status replacement written in Typescript. Built with first class support for javascript blocks.|https://github.com/mrkmg/ty3status|{{AUR|ty3status-git}}}}<br />
* {{App|i3status-rust|Highly efficient and feature-rich replacement written in Rust. Can handle push updates, individual update intervals, theming and click events|https://github.com/greshake/i3status-rust|{{Pkg|i3status-rust}} {{AUR|i3status-rust-git}}}}<br />
<br />
==== i3status wrappers ====<br />
<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.|https://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}<br />
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Pkg|py3status}}}}<br />
* {{App|YaGoStatus|Yet Another i3status replacement written in Go.|https://github.com/burik666/yagostatus|{{AUR|yagostatus-git}}}}<br />
<br />
==== Iconic fonts in the status bar ====<br />
<br />
To enable titlebar icon support install {{AUR|i3-wm-iconpatch}}. You can also use iconic font sets instead.<br />
<br />
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [https://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|https://fortawesome.github.io/Font-Awesome/|{{Pkg|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.|https://kageurufu.net/icons.pdf|{{AUR|ttf-font-icons}}}}.<br />
* {{App|ttf-ionicons|The premium icon font for Ionic Framework.|https://ionicframework.com/docs/ionicons/|{{Pkg|ttf-ionicons}}}}.<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/1.46/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|C-x}}, {{ic|8}}, {{ic|RET}}, {{ic|f004}}, {{ic|RET}}<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 {{man|1|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, set the {{ic|$TERMINAL}} [[environment variable]].<br />
<br />
=== Disable title click ===<br />
<br />
Add {{ic|bindsym button1 nop}} to not select a window when you click on it's title frame. Useful if your default layout is tabbed and you often miss click i3's tabs instead of something in an application.<br />
<br />
== Tips and tricks ==<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/OliverUv/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://github.com/davatorium/rofi|{{Pkg|rofi}}}}<br />
*{{App|i3-easyfocus|Focus and select windows in ''i3''|https://github.com/cornerman/i3-easyfocus|{{AUR|i3-easyfocus-git}}}}<br />
*{{App|wmfocus|Focus and select windows in ''i3'' and other window managers|https://github.com/svenstaro/wmfocus|{{Pkg|wmfocus}}}}<br />
*{{App|i3-cycle-focus|Provides an Alt-Tab functionality for ''i3''|https://github.com/acrisci/i3ipc-python/blob/master/examples/i3-cycle-focus.py||}}<br />
*{{App|i3-winmotion|Focus and select visible windows in ''i3''|https://github.com/iiKoe/i3-winmotion||}}<br />
<br />
=== Jump to urgent window ===<br />
<br />
Add to {{ic|~/.config/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 a 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 [https://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 > ~/.config/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|~/.config/i3/workspace_N.json}}.<br />
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|tail -n +2 ~/.config/i3/workspace_N.json {{!}} fgrep -v '// split' {{!}} sed 's{{!}}//{{!}}{{!}}g' > ~/.config/i3/workspace_N.json}}<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|~/.config/i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [https://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 ~/.config/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 workspaces 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 workspace N to workspace M<br />
i3-msg "workspace M; append_layout ~/.config/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 workspace 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|~/.config/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 [https://i3wm.org/docs/layout-saving.html#_editing_layout_files official documentation]. The ''swallows'' sections of {{ic|~/.config/i3/workspace_N.json}} needs to be manually edited.}}<br />
<br />
=== Scratchpad containers ===<br />
<br />
By default, [https://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 />
=== Screensaver and power management ===<br />
<br />
With [[Power management#xss-lock]] you can register a screenlocker for your ''i3'' session. The {{ic|-time}} option with ''xautolock'' locks the screen after a given time period:<br />
<br />
xautolock -time 10 -locker "i3lock -i 'background_image.png'" &<br />
<br />
A [[systemd]] service file can be used to lock the screen before the system is being sent to sleep or hibernation state. See [[Power management#Suspend/resume service files]]. Note that i3lock requires the type of service to be {{ic|forking}}.<br />
<br />
See also [[DPMS]].<br />
<br />
Another option is to use {{AUR|xidlehook}} with {{AUR|betterlockscreen}} or any other screensaver. ''xidlehook'' is a ''xautolock'' replacement written in [[Rust]], but with a few extra features. This includes the option to disable locking when audio is playing or when the screen is in full screen. The {{ic|--timer}} option is given in seconds:<br />
<br />
xidlehook --not-when-audio --not-when-fullscreen --timer 360 "betterlockscreen -l dim" "" &<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 behavior, 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 />
=== Swallow terminal window ===<br />
<br />
Similarly to [[dwm]], i3 can "swallow" the current terminal window with the new GUI window launched from it. This can be done through the use of the {{AUR|i3-swallow}}{{Broken package link|package not found}} or {{AUR|i3-swallow-git}} package.<br />
<br />
For example, to let [[mpv]]'s window swallow the originating terminal:<br />
<br />
$ i3-swallow mpv ''video.mp4''<br />
<br />
=== External displays manual management ===<br />
<br />
Thanks to [[xrandr]] there are many ways to easily manage systems displays. The below example integrates it in the ''i3'' config file, and behave as the Power Management section above.<br />
<br />
Here a laptop with both VGA and HDMI outputs will use a menu selection to switch them On/Off:<br />
<br />
## Manual management of external displays<br />
# Set the shortcuts and what they do<br />
set $mode_display Ext Screen (v) VGA ON, (h) HDMI ON, (x) VGA OFF, (y) HDMI OFF<br />
mode "$mode_display" {<br />
bindsym v exec --no-startup-id xrandr --output VGA1 --auto --right-of LVDS1, mode "default"<br />
bindsym h exec --no-startup-id xrandr --output HDMI1 --auto --right-of LVDS1, mode "default"<br />
bindsym x exec --no-startup-id xrandr --output VGA1 --auto --off, mode "default"<br />
bindsym y exec --no-startup-id xrandr --output HDMI1 --auto --off, mode "default"<br />
<br />
# back to normal: Enter or Escape<br />
bindsym Return mode "default"<br />
bindsym Escape mode "default"<br />
}<br />
# Declare here the shortcut to bring the display selection menu<br />
bindsym $mod+x mode "$mode_display"<br />
<br />
Any window that is still open in a switched Off display will automatically come back to the remaining active display.<br />
<br />
The simplest way to determine names of your devices is to plug the device you wish to use and run:<br />
<br />
$ xrandr --query<br />
<br />
which will output the available, recognized devices and their in-system names to set your config file appropriately. <br />
<br />
Refer to the [[xrandr]] page or man page for the complete list of available options, the [https://i3wm.org/docs/userguide.html i3 userguide] and/or the [https://www.reddit.com/r/i3wm i3 FAQ on reddit] for more info.<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:<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 [https://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 [https://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 [https://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 in statusbar ===<br />
<br />
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/net-speed.sh 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 />
=== Automatically switch horizontal / vertical window split orientation ===<br />
<br />
The {{AUR|autotiling}} package can be used for automatic switching horizontal / vertical window split orientation resulting in a similar behavior to the spiral tiling of bspwm. After installation add the following to your {{ic|~/.config/i3/config}} and reload i3.<br />
<br />
exec_always --no-startup-id ''autotiling''<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. [https://i3wm.org/docs/debugging.html] See also [[Debugging/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 [https://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 not properly implement double buffering [https://github.com/i3/i3/issues/661] hence tearing or flickering may occur. See [[picom]].<br />
<br />
=== Tray icons not visible ===<br />
<br />
The {{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 no longer adds this directive to the configuration from ''i3'' 4.12.<br />
<br />
=== Default workspace for Spotify ===<br />
<br />
To assign a default workspace for spotify windows one cannot use the standard route with {{ic|assign}} and should rather use a {{ic|for_window}} command, such as<br />
{{hc|~/.config/i3/config|2=<br />
...<br />
for_window [class="Spotify"] move container to workspace $ws10<br />
}}<br />
<br />
To ensure {{ic|for_window}} does not move the window if already in {{ic|$ws10}}, one can instead use {{ic|move --no-auto-back-and-forth}}.<br />
<br />
== See also ==<br />
<br />
* [https://i3wm.org Official website]<br />
* [[Funtoo:I3 Tiling Window Manager]]<br />
* [https://github.com/i3/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 />
* [https://j4tools.github.io/ 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 />
* [https://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]<br />
* [https://www.youtube.com/watch?v=j1I63wGcvU4&index=1&list=PL5ze0DjYv5DbCv9vNEzFmP6sU7ZmkGzcf i3 window manager v4.1X screencasts]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Talk:Arch-based_distributions&diff=692310Talk:Arch-based distributions2021-08-21T01:06:58Z<p>Thiagowfx: add system rescue cd</p>
<hr />
<div>== Excluded projects ==<br />
<br />
Following projects are excluded since they were found to misuse the [[DeveloperWiki:TrademarkPolicy|Arch Linux trademark]]:<br />
<br />
* 3du Arch, [https://sourceforge.net/projects/threeduarch/]<br />
* Arch Installer, [https://devmasters.pl/archinstaller/]<br />
* Arch Rescue Kit, [https://sourceforge.net/projects/archrescue/]<br />
* Arch USB OS, [https://sourceforge.net/projects/arch-linux-usb-os/]<br />
* CondresOS, [https://sourceforge.net/projects/condres-os-gnu-linux/], [https://www.codelinsoft.it/sito/support/wiki/how-to-switch-from-condres-to-archlinux-without-problems.html]<br />
* Happy Hacking Linux, [http://kodfabrik.com/happy-hacking-linux/]<br />
* Namib, [https://sourceforge.net/projects/namib-gnu-linux/], [https://www.namiblinux.org/]<br />
* Reborn OS, [https://sourceforge.net/projects/rebornos/]<sup>on screenshots, *2017, previously Antergos Deepin</sup><br />
* Zen Installer, [https://sourceforge.net/projects/revenge-installer/] <sup>*2016, previously OBRevenge, Revenge OS</sup><br />
<br />
If trademark misuse problems have been addressed since, please create a separate thread below.<br />
<br />
-- [[ArchWiki:Maintenance Team]]<br />
<br />
== instantOS ==<br />
<br />
instantOS is a power-user friendly Arch based distro that started in March 2019.<br />
<br />
https://instantos.io<br />
https://github.com/instantOS/instantOS<br />
<br />
[[User:Shiftgeist|Shiftgeist]] ([[User talk:Shiftgeist|talk]]) 11:01, 1 September 2020 (UTC)<br />
<br />
== CyberOS ==<br />
<br />
CyberOS is basically a community maintained project. Website: https://getcyberos.org/ And Github: https://git.omame.tech/CyberOS/<br />
— [[User:Windowsboy111|windowsboy111]] ([[User Talk:Windowsboy111|talk]]) 11:34, 26 May 2021 (UTC)<br />
<br />
== miraclx/ArtanOS ==<br />
<br />
I have been fixing a few dead links and unfortunately there are very few traces left of miraclx OS/ArtanOS.<br />
<br />
If you have any clues to where it went, please help us find a non-dead URL! Unfortunately none of the pages were archived by the Wayback Machine, most likely because they were hosted on github and gitlab before these were archived as a whole. The "best" clue I found so far is https://github.com/miraclx/artlock-classic but all the relevant links in there are dead and not archived.<br />
<br />
-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 07:56, 27 July 2021 (UTC)<br />
<br />
== <s>Update the links to the websites of active projects</s> ==<br />
<br />
A lot of links to the active projects point to SourceForge instead of the official websites of the distros. I went and made a list with the updated links. I also updated some of the names to be in line with the official ones (ex: Manjaro Linux -> Manjaro).<br />
* [https://anarchyinstaller.gitlab.io/ Anarchy]<br />
* [https://archbang.org/ ArchBang]<br />
* [https://archex.exton.net/ ArchEX]<br />
* [https://archlabslinux.com/ ArchLabs Linux]<br />
* [https://archman.org/ Archman Linux]<br />
* [https://www.xferience.org/ Arch XFerience]<br />
* [https://arcolinux.com/ ArcoLinux]<br />
* [https://artixlinux.org/ Artix Linux]<br />
* [https://www.chakralinux.org/ Chakra]<br />
* [https://ctlos.github.io/ Ctlos Linux]<br />
* [https://endeavouros.com/ EndeavourOS]<br />
* [https://garudalinux.org/ Garuda Linux]<br />
* [https://kaosx.us/ KaOS]<br />
* [https://manjaro.org/ Manjaro]<br />
* [https://www.msys2.org/ MSYS2]<br />
* [https://ninjaos.org/ Ninja OS]<br />
* [http://raspex.exton.se/ RaspArch]<br />
* [https://tearch-linux.github.io/ TeArch Linux]<br />
<br />
[[User:Silejonu|Silejonu]] ([[User talk:Silejonu|talk]]) 10:30, 19 August 2021 (UTC)Silejonu<br />
<br />
:As the page says, "SourceForge project links are preferred to simplify maintenance." Closing. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:45, 19 August 2021 (UTC)<br />
<br />
== <s>Netrunner Rolling is inactive</s> ==<br />
<br />
Netrunner Rolling has seen its last release on 2018-08-05, and the project has been confirmed to be discontinued by the development team: https://www.netrunner.com/release-schedule/<br />
<br />
[[User:Silejonu|Silejonu]] ([[User talk:Silejonu|talk]]) 10:30, 19 August 2021 (UTC)Silejonu<br />
<br />
:Seems the last release was in 2019-04-20, anyway, I've moved it to the inactive section. Thanks. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:57, 19 August 2021 (UTC)<br />
<br />
== System Rescue CD ==<br />
<br />
As per https://www.system-rescue.org/Changes-x86/, 6.0.0) 2019-02-02: "System is now based on ArchLinux and built using archiso and its dependencies"<br />
<br />
[[User:Thiagowfx|Thiagowfx]] ([[User talk:Thiagowfx|talk]]) 01:06, 21 August 2021 (UTC)</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Derivatives&diff=692309Derivatives2021-08-21T01:05:47Z<p>Thiagowfx: fix double redirect</p>
<hr />
<div>#REDIRECT [[Arch-based distributions]]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Derivatives&diff=692308Derivatives2021-08-21T01:05:14Z<p>Thiagowfx: create this redirect</p>
<hr />
<div>#REDIRECT [[Arch Derivatives]]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Zswap&diff=691988Zswap2021-08-17T03:14:09Z<p>Thiagowfx: /* Toggling zswap */ remove line, it's out-of-date. No point in updating it, it will get outdated again</p>
<hr />
<div>[[Category:Kernel]]<br />
[[ja:Zswap]]<br />
{{Related articles start}}<br />
{{Related|Kernel parameters}}<br />
{{Related|Mkinitcpio}}<br />
{{Related articles end}}<br />
[[Wikipedia:zswap|Zswap]] is a kernel feature that provides a compressed RAM cache for swap pages. <br />
Pages which would otherwise be swapped out to disk are instead compressed and stored into a memory pool in RAM. Once the pool is full or the RAM is exhausted, the least recently used ([[Wikipedia:Cache_replacement_policies#Least_recently_used_(LRU)|LRU]]) page is decompressed and written to disk, as if it had not been intercepted. After the page has been decompressed into the swap cache, the compressed version in the pool can be freed.<br />
<br />
The [[Improving performance#zram_or_zswap|difference compared to zram]] is that zswap works in conjunction with a [[swap]] device while ''zram'' is a swap device in RAM that does not require a backing swap device.<br />
<br />
== Toggling zswap ==<br />
<br />
In the stable {{Pkg|linux}} official kernel, zswap is enabled by default. This can be verified via the {{ic|CONFIG_ZSWAP_DEFAULT_ON}} flag in the [https://github.com/archlinux/svntogit-packages/blob/packages/linux/trunk/config stable kernel config].<br />
<br />
To disable zswap at runtime, execute the following command:<br />
# echo 0 > /sys/module/zswap/parameters/enabled<br />
<br />
To disable zswap permanently, add {{ic|1=zswap.enabled=0}} to your [[kernel parameters]].<br />
<br />
{{Tip|Alternatively, you can use {{pkg|systemd-swap}} which is a script to manage swap spaces with a configuration file {{ic|/etc/systemd/swap.conf}}. In this case you must [[start/enable]] {{ic|systemd-swap.service}}.}}<br />
<br />
== Customizing zswap ==<br />
<br />
=== Current parameters ===<br />
<br />
Zswap has several customizable parameters. The live settings can be displayed using:<br />
<br />
{{hc|$ grep -R . /sys/module/zswap/parameters|<br />
/sys/module/zswap/parameters/same_filled_pages_enabled:Y<br />
/sys/module/zswap/parameters/enabled:Y<br />
/sys/module/zswap/parameters/max_pool_percent:20<br />
/sys/module/zswap/parameters/compressor:lz4<br />
/sys/module/zswap/parameters/zpool:z3fold<br />
/sys/module/zswap/parameters/accept_threshold_percent:90<br />
}}<br />
<br />
See the [https://www.kernel.org/doc/html/latest/vm/zswap.html zswap documentation] for the description of the different parameters.<br />
<br />
The boot time load message showing the initial configuration can be retrieved with:<br />
<br />
{{hc|# dmesg {{!}} grep zswap:|<br />
[ 0.317569] zswap: loaded using pool lz4/z3fold<br />
}}<br />
<br />
=== Set parameters ===<br />
<br />
==== Using sysfs ====<br />
<br />
Each setting can be changed at runtime via the [[Wikipedia:sysfs|sysfs]] interface. For example, to change the {{ic|compressor}} parameter:<br />
# echo lz4 > /sys/module/zswap/parameters/compressor<br />
<br />
==== Using kernel boot parameters ====<br />
<br />
To persist the parameter change, the corresponding option, for example {{ic|1=zswap.compressor=lz4}}, must be added to the kernel boot parameter. Therefore to set permanently all the above settings, the following kernel parameters must be added: <br />
<br />
zswap.enabled=1 zswap.compressor=lz4 zswap.max_pool_percent=20 zswap.zpool=z3fold<br />
<br />
When changing the compression algorithm via boot parameter, one needs to ensure the corresponding compression module is loaded early during boot (refer to [[#Compression algorithm]]).<br />
<br />
==== Using systemd-swap ====<br />
<br />
For the ones using the ''systemd-swap'' script, it modifies the ''sysfs'' parameters at a later stage of the boot process based on its [https://github.com/Nefelim4ag/systemd-swap/blob/master/include/swap-default.conf configuration] stored in {{ic|/etc/systemd/swap.conf}}.<br />
<br />
=== Maximum pool size ===<br />
<br />
The memory pool is not preallocated, it is allowed to grow up to a certain limit in percentage of the total memory available, by default up to 20% of the total RAM. Once this threshold is reached, pages are evicted from the pool into the swap device.<br />
The maximum compressed pool size is controlled with the parameter {{ic|max_pool_percent}}.<br />
<br />
=== Compressed memory pool allocator ===<br />
<br />
The ''zpool'' parameter controls the management of the compressed memory pool.<br />
<br />
With the ''zbud'' data allocator, 2 compressed objects are stored into 1 page which limits the compression ratio to 2 or less.<br />
<br />
The superior [https://www.kernel.org/doc/html/latest/vm/z3fold.html z3fold] allocator allows up to 3 compressed objects by page. The compression ratio with ''z3fold'' typically averages 2.7 while it is 1.7 for ''zbud''.<br />
<br />
A ''zpool'' of type ''z3fold'' is created by default. Use the kernel parameter {{ic|zswap.zpool}} to select another method at boot time. The data allocator can also be changed at a later stage via the ''sysfs'' interface.<br />
<br />
=== Compression algorithm ===<br />
<br />
For page compression, zswap uses compressor modules provided by the kernel's cryptographic API. It uses by default the ''lz4'' compression algorithm but this can be changed with {{ic|1=zswap.compressor}} at boot time. Other options include ''deflate'', ''lz4hc'', ''lzo'', ''lzo-rle'', ''842'' and ''zstd''.<br />
<br />
There is no issue changing the compression at runtime using ''sysfs'' or via ''systemd-swap'' but zswap starts in this case with ''lz4'' and switches at a later stage to the defined algorithm. To start zswap with another algorithm straight away, this must be set via the kernel boot parameters and the corresponding module must be loaded early by the kernel. This can be achieved by following these steps:<br />
<br />
#Add the modules related to the chosen compressor to the [[mkinitcpio#MODULES]] array.<br />
#Regenerate the ramdisk environments after modifying mkinitcpio configuration: see [[mkinitcpio#Image creation and activation]].<br />
#Set {{ic|1=zswap.compressor}} to your chosen algorithm in the [[kernel parameters]].<br />
<br />
On next boot, see [[#Current parameters]] to check if zswap now uses the requested compressor.<br />
<br />
== See also ==<br />
<br />
* [https://lkml.org/lkml/2013/7/17/147 zswap: How to determine whether it is compressing swap pages?].<br />
* [https://www.ibm.com/developerworks/community/blogs/fe313521-2e95-46f2-817d-44a4f27eba32/entry/new_linux_zswap_compression_functionality7?lang=en IBM Developer Works Article (with benchmarks)].<br />
* [https://askubuntu.com/questions/471912/zram-vs-zswap-vs-zcache-ultimate-guide-when-to-use-which-one Ask Ubuntu: zram vs. zswap vs. zcache].<br />
* [https://bbs.archlinux.org/viewtopic.php?id=169585 Archlinux forum thread].<br />
* [https://lwn.net/Articles/537422/ LWN.net technical article by the main developer of zswap].</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Rofi&diff=691987Rofi2021-08-17T02:52:34Z<p>Thiagowfx: /* Rofi as dmenu replacement */ lines 2 -> 1</p>
<hr />
<div>[[Category:Application launchers]]<br />
[[ja:Rofi]]<br />
[[pl:Rofi]]<br />
[[pt:Rofi]]<br />
[[ru:Rofi]]<br />
{{Related articles start}}<br />
{{Related|List of applications/Other#Application launchers}}<br />
{{Related articles end}}<br />
<br />
[https://github.com/DaveDavenport/rofi Rofi] is a window switcher, run dialog, ssh-launcher and [[dmenu]] replacement that started as a clone of [https://github.com/seanpringle/simpleswitcher simpleswitcher], written by [https://github.com/seanpringle Sean Pringle] and later expanded by [https://github.com/DaveDavenport Dave Davenport].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|rofi}} package.<br />
<br />
== Configuration ==<br />
<br />
There are currently three methods of setting configuration options:<br />
<br />
* Local configuration. Normally, depending on XDG, in {{ic|~/.config/rofi/config.rasi}}.<br />
* Xresources: A method of storing key values in the Xserver.<br />
* Command line options<br />
<br />
{{Note|Xresources format is obsolete since rofi 1.6.0 and may stop working at any time. }}<br />
<br />
So<br />
<br />
$ rofi -combi-modi window,drun,ssh -theme solarized -font "hack 10" -show combi<br />
<br />
can be expressed in a config file like this (New theme format):<br />
<br />
configuration {<br />
modi: "window,drun,ssh,combi";<br />
theme: "solarized";<br />
font: "hack 10";<br />
combi-modi: "window,drun,ssh";<br />
}<br />
<br />
To get a full list of options for {{ic|config.rasi}} file run {{ic|rofi -dump-config}}. You can write the output of the command directly to your {{ic|config}} file while running {{ic|rofi -dump-config > ~/.config/rofi/config.rasi}}<br />
<br />
{{Note|i3 users be aware that putting commas in i3 config can cause issues. To bind a key to launch rofi, either use a config file or replace the commas with {{ic|#}} eg {{ic|rofi -combi-modi window#drun#ssh}}}}<br />
<br />
=== Icons ===<br />
<br />
It is possible to use icons to display with their corresponding entries. Assuming you have {{pkg|papirus-icon-theme}} installed, with {{ic|-show-icons}} and defining the icon theme with {{ic|-icon-theme}}, you can have rofi display icons and do the following:<br />
<br />
$ rofi -combi-modi window,drun,ssh -theme solarized -font "hack 10" -show combi -icon-theme "Papirus" -show-icons<br />
<br />
==Rofi as dmenu replacement==<br />
<br />
If called as dmenu (via a symlink), rofi acts like dmenu. You may want to install {{AUR|rofi-dmenu}}, which symlinks dmenu to rofi. Then programs that call dmenu from a script (like passmenu from [[pass]]) will use rofi instead of dmenu.<br />
<br />
If you prefer the look of dmenu, this approximates it:<br />
<br />
rofi -show run -modi run -location 1 -width 100 \<br />
-lines 1 -line-margin 0 -line-padding 1 \<br />
-separator-style none -font "mono 10" -columns 9 -bw 0 \<br />
-disable-history \<br />
-hide-scrollbar \<br />
-color-window "#222222, #222222, #b1b4b3" \<br />
-color-normal "#222222, #b1b4b3, #222222, #005577, #b1b4b3" \<br />
-color-active "#222222, #b1b4b3, #222222, #007763, #b1b4b3" \<br />
-color-urgent "#222222, #b1b4b3, #222222, #77003d, #b1b4b3" \<br />
-kb-row-select "Tab" -kb-row-tab ""<br />
<br />
==Execute shell commands from rofi==<br />
<br />
If you want the ability to run shell commands or use your own scripts directly from rofi with seeing the output, then ensure following:<br />
* configure the PATH variable in {{ic|~/.profile}} (instead of e.g. {{ic|~/.bashrc}}) and then logout and re-login to your window manager/desktop environment<br />
* define {{ic|-run-shell-command '{terminal} -e \\"{cmd}; read -n 1 -s"'}}. This allows you to enter the command on the inputbar followed by SHIFT+ENTER. The terminal stays open until the next keypress.<br />
<br />
This is an example with the recommended escaping sequence for i3:<br />
<br />
bindsym $mod+d exec --no-startup-id "rofi -show drun -font \\"DejaVu 9\\" -run-shell-command '{terminal} -e \\" {cmd}; read -n 1 -s\\"'"<br />
<br />
==Custom Themes==<br />
<br />
You can preview and apply themes for rofi with<br />
<br />
rofi-theme-selector<br />
<br />
Customizations may be saved to your [[X_resources|.Xresources file]] (requires the {{pkg|xorg-xrdb}} package).<br />
To apply changes reload .Xresources with {{ic|xrdb -load ~/.Xresources}}.<br />
<br />
===Contributed Themes===<br />
<br />
Rofi comes with several official themes, and more user themes can be found at the [https://github.com/DaveDavenport/rofi-themes rofi-themes] repository.<br />
<br />
Load up an official theme, or download a .rasi user theme and place it in {{ic|~/.config/rofi/example.rasi}} on the command line or in a config file:<br />
<br />
rofi <options> -theme example<br />
<br />
or in your configuration file<br />
<br />
theme: "example";</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Firmware&diff=691866Firmware2021-08-16T15:25:13Z<p>Thiagowfx: add redirect to fwupd, seems more canonical. When users search for firmware they are usually interested in firmware updates</p>
<hr />
<div>#REDIRECT [[fwupd]]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=User:Thiagowfx&diff=690406User:Thiagowfx2021-08-02T15:52:43Z<p>Thiagowfx: add github</p>
<hr />
<div>== Arch ==<br />
* [[Arch is the best]]<br />
* [https://xyne.archlinux.ca/etc/dyn/img/graphviz/Arch_Linux_Help_Guide.svg Xyne's Arch Linux Help Guide]<br />
<br />
== My profiles ==<br />
* [https://aur.archlinux.org/packages/?SeB=m&K=thiagowfx AUR]<br />
* [https://bbs.archlinux.org/profile.php?id=73061 BBS]<br />
* [https://bugs.archlinux.org/user/17059 Bugtracker]<br />
* [https://github.com/thiagowfx Github]<br />
<br />
== Subpages ==<br />
{{Special:PrefixIndex/{{FULLPAGENAME}}/}}</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Dotfiles&diff=690306Dotfiles2021-08-02T02:24:14Z<p>Thiagowfx: /* User repositories */ update my dotfiles</p>
<hr />
<div>[[Category:Configuration files]]<br />
[[Category:Configuration management]]<br />
[[es:Dotfiles]]<br />
[[ja:ドットファイル]]<br />
[[pt:Dotfiles]]<br />
{{Related articles start}}<br />
{{Related|XDG Base Directory support}}<br />
{{Related|X resources}}<br />
{{Related articles end}}<br />
User-specific application configuration is traditionally stored in so called [[Wikipedia:dotfile|dotfiles]] (files whose filename starts with a dot). It is common practice to track dotfiles with a [[version control system]] such as [[Git]] to keep track of changes and synchronize dotfiles across various hosts. There are various approaches to managing your dotfiles (e.g. directly tracking dotfiles in the home directory v.s. storing them in a subdirectory and symlinking/copying/generating files with a [[shell]] script or [[#Tools|a dedicated tool]]). Apart from explaining how to manage your dotfiles this article also contains [[#User repositories|a list of dotfile repositories]] from Arch Linux users.<br />
<br />
== Tracking dotfiles directly with Git ==<br />
<br />
The benefit of tracking dotfiles directly with Git is that it only requires [[Git]] and does not involve symlinks. The disadvantage is that [[#Host-specific configuration|host-specific configuration]] generally requires merging changes into multiple [[Git#Branching|branches]].<br />
<br />
The simplest way to achieve this approach is to initialize a [[Git]] repository directly in your home directory and ignoring all files by default with a {{man|5|gitignore}} pattern of {{ic|*}}. This method however comes with two drawbacks: it can become confusing when you have other Git repositories in your home directory (e.g. if you forget to initialize a repository you suddenly operate on your dotfile repository) and you can no longer easily see which files in the current directory are untracked (because they are ignored).<br />
<br />
An alternative method without these drawbacks is the "bare repository and alias method" popularized on [https://news.ycombinator.com/item?id=11071754 Ask Hacker News: What do you use to manage your dotfiles?], which just takes three commands to set up:<br />
<br />
$ git init --bare ~/.dotfiles<br />
$ alias config='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'<br />
$ config config status.showUntrackedFiles no<br />
<br />
You can then manage your dotfiles with the created [[alias]]. If you are using [[Bash]] and would like bash completion for this alias, simply install {{AUR|bash-complete-alias}}, then add the alias and the following line to your {{ic|~/.bashrc}}.<br />
<br />
$ complete -F _complete_alias config<br />
<br />
{{Tip|To avoid accidentally commiting confidential information, see [[Git#Filtering confidential information]].}}<br />
<br />
== Host-specific configuration ==<br />
<br />
A common problem with synchronizing dotfiles across various machines is host-specific configuration.<br />
<br />
With [[Git]] this can be solved by maintaining a master branch for all shared configuration, while each individual machine has a machine-specific branch checked out. Host-specific configuration can be committed to the machine-specific branch; when shared configuration is modified in the master branch, the per-machine branches need to be rebased on top of the updated master.<br />
<br />
In configuration scripts like [[Command-line shell#Configuration files|shell configuration files]] conditional logic can be used. For example, [[Bash]] scripts (i.e. {{ic|.bashrc}}) can apply different configuration depending on the machine name (or type, custom variable, etc.):<br />
<br />
if <nowiki>[[ "$(hostname)" == "archlaptop" ]];</nowiki> then<br />
# laptop specific commands here<br />
else<br />
# desktop or server machine commands<br />
fi<br />
<br />
Similar can also be achieved with [[.Xresources]].[https://jnrowe.github.io/articles/tips/Sharing_Xresources_between_systems.html]<br />
<br />
If you find rebasing Git branches too cumbersome, you may want to use a [[#Tools|tool]] that supports ''file grouping'', or if even greater flexibility is desired, a tool that does ''processing''.<br />
<br />
== Tools ==<br />
<br />
;File grouping<br />
:How configuration files can be grouped to configuration groups (also called profiles or packages).<br />
;Processing<br />
:Some tools process configuration files to allow them to be customized depending on the host.<br />
<br />
{| class="wikitable sortable" style="text-align: center;"<br />
! Name !! Package !! Written in !! File grouping !! Processing<br />
|-<br />
! [https://github.com/kesslern/dot-templater dot-templater]<br />
| {{AUR|dot-templater-git}} || Rust || directory-based || custom syntax<br />
|-<br />
! [https://github.com/SuperCuber/dotter dotter]<br />
| {{AUR|dotter-rs}} || Rust || configuration file || Handlebars<br />
|-<br />
! [https://deadc0de.re/dotdrop/ dotdrop]<br />
| {{AUR|dotdrop}} || Python || configuration file || Jinja2<br />
|-<br />
! [https://github.com/jbernard/dotfiles dotfiles]<br />
| {{AUR|dotfiles}} || Python || {{Grey|[https://github.com/jbernard/dotfiles/pull/24 No]}} || {{Grey|No}}<br />
|-<br />
! [https://github.com/EvanPurkhiser/dots Dots]<br />
| {{AUR|dots-manager}} || Python || directory-based || custom append points<br />
|-<br />
! [https://github.com/twpayne/chezmoi chezmoi]<br />
| {{Pkg|chezmoi}} || Go || directory-based || Go templates<br />
|-<br />
! [https://www.gnu.org/software/stow/ GNU Stow]<br />
| {{Pkg|stow}} || Perl || directory-based[http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html] || {{Grey|No}}<br />
|-<br />
! [https://github.com/lra/mackup Mackup]<br />
| {{AUR|mackup}} || Python || automatic per application || {{Grey|No}}<br />
|-<br />
! [https://github.com/darkfeline/mir.qualia mir.qualia]<br />
| {{AUR|mir.qualia}} || Python || {{Grey|No}} || custom blocks<br />
|-<br />
! [https://github.com/thoughtbot/rcm rcm]<br />
| {{AUR|rcm}} || Perl || directory-based (by host or tag) || {{Grey|No}}<br />
|}<br />
<br />
=== Tools wrapping Git ===<br />
<br />
If you are uncomfortable with [[Git]], you may want to use one of these tools, which abstract the version control system away (more or less).<br />
<br />
{| class="wikitable sortable" style="text-align:center;"<br />
! Name !! Package !! Written in !! File grouping !! Processing<br />
|-<br />
! [https://github.com/kazhala/dotbare dotbare]<br />
| {{AUR|dotbare}} || Shell ({{Pkg|fzf}}) || repository-wise || {{Grey|No}}<br />
|-<br />
! [https://github.com/kobus-v-schoor/dotgit dotgit]<br />
| {{AUR|dotgit}} || Python || filename-based || {{Grey|No}}<br />
|-<br />
! [https://github.com/andsens/homeshick homeshick]<br />
| {{AUR|homeshick-git}} || Bash || repository-wise || {{Grey|No}}<br />
|-<br />
! [https://github.com/technicalpickles/homesick homesick]<br />
| {{-}} || Ruby || repository-wise || {{Grey|No}}<br />
|-<br />
! [https://github.com/pearl-core/pearl Pearl]<br />
| {{AUR|pearl-git}} || Python || repository-wise || {{Grey|No}}<br />
|-<br />
! [https://github.com/RichiH/vcsh vcsh]<br />
| {{AUR|vcsh}} || Shell || repository-wise || {{Grey|No}}<br />
|-<br />
! [https://yadm.io yadm]<sup>(1)</sup><br />
| {{AUR|yadm}} || Bash || filename-based<br>(by class/OS/distro/hostname/user)[https://yadm.io/docs/alternates] ||Built-in templates/Jinja2/ESH[https://yadm.io/docs/templates]<br>(optional)<br />
|}<br />
<br />
# Supports encryption of confidential files with [[GPG]] or OpenSSL. [https://yadm.io/docs/encryption]<br />
<br />
== User repositories ==<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! Author || Shell (Shell framework) || WM / DE || Editor || Terminal || Multiplexer || Audio || Monitor || Mail || IRC || File Manager<br />
|-<br />
! [https://github.com/alfunx/.dotfiles alfunx]<br />
| zsh || awesome || vim || kitty || tmux || ncmpcpp/mpd || htop/lain || thunderbird || ||<br />
|-<br />
! [https://gitlab.com/Ambrevar/dotfiles Ambrevar]<br />
| Eshell || EXWM || Emacs || Emacs (Eshell) || Emacs TRAMP + dtach || EMMS || conky/dzen || mu4e || Circe ||<br />
|-<br />
! [https://github.com/ask1234560/dotfiles_bspwm ananthu]<br />
| zsh || bspwm || neovim || alacritty || || mpv || htop, polybar || neomutt || weechat || ranger<br />
|-<br />
! [https://github.com/awalGarg/dotfiles awal]<br />
| fish || i3 || vim || st || tmux || || i3status || || The Lounge ||<br />
|-<br />
! [https://github.com/ayekat/dotfiles ayekat]<br />
| zsh || karuiwm || vim || rxvt-unicode || tmux || ncmpcpp/mpd || karuibar || mutt || irssi ||<br />
|-<br />
! [https://github.com/BachoSeven/dotfiles bachoseven]<br />
| zsh || [https://github.com/BachoSeven/dwm dwm] || neovim || [https://github.com/BachoSeven/st st] || || ncmpcpp || bottom || neomutt || weechat || lf<br />
|-<br />
! [https://github.com/bamos/dotfiles bamos]<br />
| zsh || i3/xmonad || vim/emacs || rxvt-unicode || tmux || mpv/cmus || conky/xmobar || mutt || ERC ||<br />
|-<br />
! [https://github.com/benmezger/dotfiles benmezger] <br />
| [https://github.com/benmezger/dotfiles zsh/bash/fish] || [https://github.com/benmezger/dotfiles/tree/main/dot_config/i3 i3-gaps] || [https://github.com/benmezger/dotfiles/tree/main/dot_doom.d emacs] || [https://github.com/benmezger/dotfiles/blob/main/dot_Xresources rxvt-unicode] || [https://github.com/benmezger/dotfiles/blob/main/dot_tmux.conf tmux] || || [https://github.com/benmezger/dotfiles/blob/main/dot_config/i3/status.toml.tmpl i3status-rs] || mu4e/neomutt || weechat ||<br />
|-<br />
! [https://github.com/pbrisbin/dotfiles brisbin33]<br />
| [https://github.com/pbrisbin/oh-my-zsh zsh] || [https://github.com/pbrisbin/xmonad-config xmonad] || [https://github.com/pbrisbin/vim-config vim] || rxvt-unicode || screen || || dzen || [https://github.com/pbrisbin/mutt-config mutt] || [https://github.com/pbrisbin/irssi-config irssi] ||<br />
|-<br />
! [https://gitlab.com/BVollmerhaus/dotfiles BVollmerhaus]<br />
| [https://gitlab.com/BVollmerhaus/dotfiles/-/tree/master/config/fish fish] || [https://gitlab.com/BVollmerhaus/dotfiles/blob/master/config/i3/config i3-gaps] || [https://gitlab.com/BVollmerhaus/dotfiles/blob/master/config/kak/kakrc kakoune] || [https://gitlab.com/BVollmerhaus/dotfiles/-/blob/master/config/kitty/kitty.conf kitty] || || || [https://gitlab.com/BVollmerhaus/dotfiles/blob/master/config/polybar/config polybar] || || || [https://gitlab.com/BVollmerhaus/dotfiles/-/tree/master/config/ranger ranger]<br />
|-<br />
! [https://github.com/cinelli/dotfiles cinelli]<br />
| zsh || dwm || vim || termite-git || || pianobar || htop || mutt-kz || weechat ||<br />
|-<br />
! [https://github.com/dikiaap/dotfiles dikiaap]<br />
| zsh || i3-gaps || neovim || alacritty || tmux || || i3blocks || || || nnn<br />
|-<br />
! [https://github.com/Earnestly/dotfiles Earnestly]<br />
| zsh || i3/orbment || vim/emacs || termite || tmux || mpd || conky || mutt || weechat ||<br />
|-<br />
! [https://github.com/ErikBjare/dotfiles ErikBjare]<br />
| zsh || xmonad/xfce4 || vim || terminator || tmux || || xfce4-panel || || weechat ||<br />
|-<br />
! [https://github.com/falconindy/dotfiles falconindy]<br />
| bash || i3 || vim || rxvt-unicode || || ncmpcpp || conky || mutt || ||<br />
|-<br />
! [https://github.com/filiparag/dotfiles filiparag]<br />
| fish || bspwm || vim || alacritty || tmux || mpv, [https://github.com/altdesktop/playerctl playerctl] || htop, polybar || [https://www.nongnu.org/mailnotify/ mail-notification] || || [https://wiki.lxde.org/en/PCManFM pcmanfm]<br />
|-<br />
! [https://git.sr.ht/~gardenapple/dotfiles gardenapple]<br />
| fish || Sway || neovim || kitty || || || htop || [https://aerc-mail.org/ aerc] || ||<br />
|-<br />
! [https://github.com/graysky2/configs/tree/master/dotfiles graysky]<br />
| zsh || xfce4 || vim || terminal || || ncmpcpp || custom || thunderbird || ||<br />
|-<br />
! [https://github.com/hugdru/dotfiles hugdru]<br />
| zsh || awesome || neovim || rxvt-unicode || tmux || || || thunderbird || weechat ||<br />
|-<br />
! [https://github.com/insanum/dotfiles insanum]<br />
| bash || herbstluftwm || vim || evilvte || tmux || || dzen || mutt-kz || ||<br />
|-<br />
! [https://github.com/isti115/dotfiles isti115]<br />
| [https://github.com/Isti115/dotfiles/blob/master/.config/powershell/Microsoft.PowerShell_profile.ps1 pwsh]<br />
|| [https://github.com/Isti115/dotfiles/blob/master/.config/sway/config sway]<br />
|| [https://github.com/Isti115/dotfiles/tree/master/.config/nvim neovim]<br />
|| [https://github.com/Isti115/dotfiles/blob/master/.config/alacritty/alacritty.yml alacritty]<br />
|| tmux<br />
|| [https://github.com/Isti115/dotfiles/tree/master/.config/mpv mpv] / playerctl<br />
|| [https://github.com/Isti115/dotfiles/tree/master/.config/waybar waybar] / htop / ytop<br />
|| <br />
|| <br />
|| [https://github.com/Isti115/dotfiles/tree/master/.config/ranger ranger]<br />
|-<br />
! [https://hg.sr.ht/~jasonwryan/shiv jasonwryan]<br />
| bash/zsh || dwm || vim || rxvt-unicode || tmux || ncmpcpp || custom || mutt || irssi ||<br />
|-<br />
! [https://github.com/JDevlieghere/dotfiles/ jdevlieghere]<br />
| zsh || xmonad || vim || terminal || tmux || || htop || mutt || weechat ||<br />
|-<br />
! [https://github.com/jelly/Dotfiles jelly]<br />
| zsh || i3 || vim || termite || tmux || ncmpcpp || || mutt-kz-git || weechat ||<br />
|-<br />
! [https://github.com/JonasDe/dotfiles JonasDe] <br />
| zsh || i3 || vim || rxvt-unicode || tmux || || || || ||<br />
|-<br />
! [https://github.com/Jorengarenar/dotfiles Jorengarenar] <br />
| bash || i3 || vim || xterm || || mpv || i3blocks || aerc || weechat ||<br />
|-<br />
! [https://github.com/markuszoppelt/dotfiles MarkusZoppelt]<br />
| zsh || gnome || vim || terminal || tmux || || || || || <br />
|-<br />
! [https://github.com/maximbaz/dotfiles maximbaz]<br />
| zsh || sway || kakoune || kitty || || || waybar || neomutt || || nnn<br />
|-<br />
! [https://git.mehalter.com/mehalter/dotfiles mehalter]<br />
| zsh || i3-gaps || neovim || termite || tmux || cmus || gotop || neomutt || weechat || ranger<br />
|-<br />
! [https://github.com/meskarune/.dotfiles meskarune]<br />
| bash || herbstluftwm || vim || rxvt-unicode || screen || || conky || || weechat ||<br />
|-<br />
! [https://github.com/neersighted/dotfiles neersighted]<br />
| fish || i3 || neovim || alacritty || tmux || ncmpcpp || || || ||<br />
|-<br />
! [https://github.com/nimaipatel/dotfiles nimaipatel]<br />
| zsh || [https://github.com/nimaipatel/dwm dwm] || neovim || [https://github.com/nimaipatel/st st] || tmux || ncmpcpp || [https://github.com/nimaipatel/dwmblocks dwmblocks] || || || ranger<br />
|-<br />
! [https://github.com/oibind/dotfiles oibind]<br />
| fish || awesome || neovim || st || tmux || || htop-vim || || weechat || lf<br />
|-<br />
! [https://github.com/ok100/configs OK100]<br />
| bash || dwm || vim || rxvt-unicode || || cmus || conky, dzen || mutt || weechat ||<br />
|-<br />
! [https://github.com/pablox-cl/dotfiles pablox-cl]<br />
| zsh (zplug) || gnome3 || neovim || kitty || || || || || ||<br />
|-<br />
! [https://gitlab.com/peterzuger/dotfiles peterzuger]<br />
| zsh || i3-gaps || emacs || rxvt-unicode || screen || moc || htop || || ||<br />
|-<br />
! [https://github.com/potamides/dotfiles potamides]<br />
| bash || awesome || neovim || termite || tmux || ncmpcpp || conky,htop || mutt || weechat || ranger<br />
|-<br />
! [https://github.com/reisub0/dot reisub0]<br />
| fish || qtile || neovim || kitty || || mpd || conky || || ||<br />
|-<br />
! [https://gitlab.com/Scrumplex/dotfiles Scrumplex]<br />
| fish || sway || neovim || kitty || || mpd || waybar || || ||<br />
|-<br />
! [https://github.com/shubhamgupta2956/dotfiles shubhamgupta2956]<br />
| zsh || i3-gaps-rounded || vim || terminator || || cmus || htop, i3blocks, gotop || || || ranger, nautilus<br />
|-<br />
! [https://github.com/sistematico/majestic sistematico]<br />
| zsh/fish/bash || [https://github.com/Airblader/i3 i3-gaps] || vim/nano || termite || tmux || ncmpcpp || polybar || mutt || weechat ||<br />
|-<br />
! [https://git.sitilge.id.lv/sitilge/dotfiles sitilge]<br />
| zsh || sway || neovim || alacritty || || || htop || thunderbird || ||<br />
|-<br />
! [https://github.com/thiagowfx/.dotfiles thiagowfx]<br />
| bash/zsh || i3 || vim || alacritty || tmux || playerctl || i3status || || || ranger<br />
|-<br />
! [https://github.com/vodik/dotfiles vodik]<br />
| zsh || xmonad || vim || termite-git || tmux || ncmpcpp || custom || mutt || weechat ||<br />
|-<br />
! [https://github.com/w0ng/dotfiles w0ng]<br />
| zsh || dwm || vim || rxvt-unicode || tmux || ncmpcpp || custom || mutt || irssi ||<br />
|-<br />
! [https://github.com/whitelynx/dotfiles whitelynx]<br />
| fish || i3 || neovim || kitty || || || i3pystatus || || ||<br />
|-<br />
! [https://github.com/wolfcore/dotfiles wolfcore] <br />
| bash || dwm || vim || rxvt-unicode || tmux || cmus || custom || || weechat ||<br />
|-<br />
! [https://github.com/zendeavor zendeavor]<br />
| [https://github.com/zendeavor/config-stuff/tree/sandbag/zsh zsh] || [https://github.com/zendeavor/config-stuff/blob/sandbag/i3/config i3] || [https://github.com/zendeavor/dotvim/tree/sandbag vim] || [https://github.com/zendeavor/config-stuff/blob/sandbag/X11/Xresources#L14 rxvt-unicode] || [https://github.com/zendeavor/config-stuff/tree/sandbag/tmux tmux] || [https://github.com/zendeavor/config-stuff/blob/sandbag/ncmpcpp/config ncmpcpp] || [https://github.com/zendeavor/config-stuff/blob/sandbag/i3/i3status.conf i3status] || || [https://github.com/zendeavor/config-stuff/tree/kiwi/weechat weechat] ||<br />
|}<br />
<br />
== See also ==<br />
<br />
* [[gregswiki:DotFiles]]<br />
* [https://wiki.haskell.org/Xmonad/Config_archive XMonad Config Archive]<br />
* [http://dotshare.it dotshare.it]<br />
* [https://dotfiles.github.io/ dotfiles.github.io]<br />
* [https://terminal.sexy/ terminal.sexy] - Terminal color scheme designer</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=690304Pacman/Tips and tricks2021-08-02T02:02:21Z<p>Thiagowfx: /* Identify files not owned by any package */ find: exclude /var/tmp/ and /var/cache directories</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[de:Pacman-Tipps]]<br />
[[es:Pacman (Español)/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Pacman (Français)/Tips and tricks]]<br />
[[it:Pacman (Italiano)/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman (Português)/Tips and tricks]]<br />
[[ru:Pacman (Русский)/Tips and tricks]]<br />
[[zh-hans:Pacman (简体中文)/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with ''pacman'' 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
==== With version ====<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all packages in the [[package group]] named {{ic|''group''}}: {{ic|pacman -Sg ''group''}}<br />
* List all foreign packages (typically manually downloaded and installed or packages removed from the repositories): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format (needs {{Pkg|expac}}): {{ic|expac -s "%-30n %v" ''regex''}}.<br />
<br />
==== With size ====<br />
<br />
Figuring out which packages are largest can be useful when trying to free space on your hard drive. There are two options here: get the size of individual packages, or get the size of packages and their dependencies.<br />
<br />
===== Individual packages =====<br />
<br />
The following command will list all installed packages and their individual sizes:<br />
<br />
$ LC_ALL=C pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4$5, name}' | sort -h<br />
<br />
===== Packages and dependencies =====<br />
<br />
To list package sizes with their dependencies,<br />
<br />
* Install {{Pkg|expac}} and run {{ic|expac -H M '%m\t%n' {{!}} sort -h}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in the [[meta package]] {{Pkg|base}} nor [[package group]] {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort | uniq)) | sort -n<br />
<br />
To list the packages marked for upgrade with their download size<br />
<br />
$ expac -S -H M '%k\t%n' $(pacman -Qqu) | sort -sh<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group, repository or meta package ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].<br />
}}<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} [[meta package]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <(expac -l '\n' '%E' base | sort)<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} meta package or {{Grp|base-devel}} [[package group]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Pkg|base}} meta package or {{Grp|base-devel}} package group:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -H M '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the {{Pkg|base}} meta package:<br />
<br />
<nowiki>$ comm -23 <(curl https://gitlab.archlinux.org/archlinux/archiso/-/raw/master/configs/releng/packages.x86_64) <(expac -l '\n' '%E' base | sort)</nowiki><br />
<br />
{{Tip|Alternatively, use {{ic|combine}} (instead of {{ic|comm}}) from the {{Pkg|moreutils}} package which has a syntax that is easier to remember. See {{man|1|combine}}.}}<br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | grep -Ee '-(bzr|cvs|darcs|git|hg|svn)$'<br />
<br />
=== Browsing packages ===<br />
<br />
To browse all installed packages with an instant preview of each package:<br />
<br />
$ pacman -Qq | fzf --preview 'pacman -Qil {}' --layout=reverse --bind 'enter:execute(pacman -Qil {} | less)'<br />
<br />
This uses [[fzf]] to present a two-pane view listing all packages with package info shown on the right.<br />
<br />
Enter letters to filter the list of packages; use arrow keys (or {{ic|Ctrl-j}}/{{ic|Ctrl-k}}) to navigate; press {{ic|Enter}} to see package info under ''less''.<br />
<br />
To browse all packages currently known to ''pacman'' (both installed and not yet installed) in a similar way, using fzf, use:<br />
<br />
$ pacman -Slq | fzf --preview 'pacman -Si {}' --layout=reverse<br />
<br />
The navigational keybindings are the same, although Enter will not work in the same way.<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs -r du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up.<br />
<br />
One method is to use {{ic|pacreport --unowned-files}} as the root user from {{Pkg|pacutils}} which will list unowned files among other details.<br />
<br />
Another is to list all files of interest and check them against ''pacman'':<br />
<br />
# find /etc /usr /opt /var -not -path "/var/tmp/*" -and -not -path "/var/cache/*" | LC_ALL=C pacman -Qqo - 2>&1 >&- >/dev/null | cut -d ' ' -f 5-<br />
<br />
{{Tip|The {{Pkg|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output.}}<br />
<br />
=== Tracking unowned files created by packages ===<br />
<br />
Most systems will slowly collect several [http://ftp.rpm.org/max-rpm/s1-rpm-inside-files-list-directives.html#S3-RPM-INSIDE-FLIST-GHOST-DIRECTIVE ghost] files such as state files, logs, indexes, etc. through the course of usual operation.<br />
<br />
{{ic|pacreport}} from {{Pkg|pacutils}} can be used to track these files and their associations via {{ic|/etc/pacreport.conf}} (see {{man|1|pacreport|FILES}}).<br />
<br />
An example may look something like this (abridged):<br />
<br />
{{hc|/etc/pacreport.conf|2=<br />
[Options]<br />
IgnoreUnowned = usr/share/applications/mimeinfo.cache<br />
<br />
[PkgIgnoreUnowned]<br />
alsa-utils = var/lib/alsa/asound.state<br />
bluez = var/lib/bluetooth<br />
ca-certificates = etc/ca-certificates/trust-source/*<br />
dbus = var/lib/dbus/machine-id<br />
glibc = etc/ld.so.cache<br />
grub = boot/grub/*<br />
linux = boot/initramfs-linux.img<br />
pacman = var/lib/pacman/local<br />
update-mime-database = usr/share/mime/magic<br />
}}<br />
<br />
Then, when using {{ic|pacreport --unowned-files}} as the root user, any unowned files will be listed if the associated package is no longer installed (or if any new files have been created).<br />
<br />
Additionally, [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) allows tracking modified and orphaned files using a configuration script.<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Qtdq | pacman -Rns -<br />
<br />
If no orphans were found, the output is {{ic|error: argument '-' specified with empty stdin}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but essential packages ===<br />
<br />
If it is ever necessary to remove all packages except the essentials packages, one method is to set the installation reason of the non-essential ones as dependency and then remove all unnecessary dependencies.<br />
<br />
First, for all the packages installed "as explicitly", change their installation reason to "as dependency":<br />
<br />
# pacman -D --asdeps $(pacman -Qqe)<br />
<br />
Then, change the installation reason to "as explicitly" of only the essential packages, those you '''do not''' want to remove, in order to avoid targeting them:<br />
<br />
# pacman -D --asexplicit base linux linux-firmware<br />
<br />
{{Note|<br />
* Additional packages can be added to the above command in order to avoid being removed. See [[Installation guide#Install essential packages]] for more info on other packages that may be necessary for a fully functional base system.<br />
* This will also select the bootloader's package for removal. The system should still be bootable, but the boot parameters might not be changeable without it.<br />
}}<br />
<br />
Finally, follow the instructions in [[#Removing unused packages (orphans)]] to remove all packages that have installation reason "as dependency".<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ LC_ALL=C pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
{{Accuracy|What is the connection of this section to [[System backup]]? Listing modified "backup files" does not show files which are not tracked by ''pacman''.|section=Warning about listing changed backup files}}<br />
<br />
If you want to back up your system configuration files, you could copy all files in {{ic|/etc/}} but usually you are only interested in the files that you have changed. Modified [[Pacnew and Pacsave files#Package backup files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows about, not only backup files.}}<br />
<br />
=== Back up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw --cachedir . base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Pacman, which will reference the host installation by default, will not properly resolve and download existing dependencies. In cases where all packages and dependencies are wanted, it is recommended to create a temporary blank DB and reference it with {{ic|--dbpath}}:<br />
<br />
# mkdir /tmp/blankdb<br />
# pacman -Syw --cachedir . --dbpath /tmp/blankdb base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. <br />
A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', ''.tar.zst'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.<br />
<br />
To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the {{man|8|vercmp}} ordering used by ''pacman''.}}<br />
<br />
If you are looking to support multiple architectures then precautions should be taken to prevent errors from occurring. Each architecture should have its own directory tree:<br />
<br />
{{hc|$ tree ~/customrepo/ {{!}} sed "s/$(uname -m)/<arch>/g"|<br />
/home/archie/customrepo/<br />
└── <arch><br />
├── customrepo.db -> customrepo.db.tar.xz<br />
├── customrepo.db.tar.xz<br />
├── customrepo.files -> customrepo.files.tar.xz<br />
├── customrepo.files.tar.xz<br />
└── personal-website-git-b99cce0-1-<arch>.pkg.tar.xz<br />
<br />
1 directory, 5 files<br />
}}<br />
<br />
The ''repo-add'' executable checks if the package is appropriate. If this is not the case you will be running into error messages similar to this:<br />
<br />
==> ERROR: '/home/archie/customrepo/<arch>/foo-<arch>.pkg.tar.xz' does not have a valid database archive extension.<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
{{Merge|Package_Proxy_Cache|Same topic}}<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver, e.g. {{Pkg|darkhttpd}}, which other computers can use as a first mirror:<br />
<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
If you are already running a web server for some other purpose, you might wish to reuse that as your local repo server instead of darkhttpd. For example, if you already serve a site with [[nginx]], you can add an nginx server block listening on port 8080:<br />
<br />
{{hc|/etc/nginx/nginx.conf|<br />
server {<br />
listen 8080;<br />
root /var/cache/pacman/pkg;<br />
server_name myarchrepo.localdomain;<br />
try_files $uri $uri/;<br />
}<br />
}}<br />
<br />
Remember to restart nginx after making this change.<br />
<br />
Whichever web server you use, remember to open port 8080 to local traffic (and you probably want to deny anything not local). For example, if using [[iptables]], add {{ic|-s 192.168.0.0/16 -p tcp --dport 8080 -j ACCEPT}} to your ruleset (adjust for your LAN subnet if necessary).<br />
<br />
==== Overlay mount of read-only cache ====<br />
<br />
It is possible to use one machine on a local network as a read-only package cache by [[Overlay_filesystem|overlay mounting]] its {{ic|/var/cache/pacman/pkg}} directory. Such a configuration is advantageous if this server has installed on it a reasonably comprehensive selection of up-to-date packages which are also used by other boxes. This is useful for maintaining a number of machines at the end of a low bandwidth upstream connection.<br />
<br />
As an example, to use this method:<br />
<br />
# mkdir /tmp/remote_pkg /mnt/workdir_pkg /tmp/pacman_pkg<br />
# sshfs <remote_username>@<remote_pkgcache_addr>:/var/cache/pacman/pkg /tmp/remote_pkg -C<br />
# mount -t overlay overlay -o lowerdir=/tmp/remote_pkg,upperdir=/var/cache/pacman/pkg,workdir=/mnt/workdir_pkg /tmp/pacman_pkg<br />
<br />
[[Overlay_filesystem#Usage|Note concerning overlay]]: The working directory must be an empty directory on the same mounted device as the upper directory.<br />
<br />
After this, run ''pacman'' using the option {{ic|--cachedir /tmp/pacman_pkg}}, e.g.:<br />
<br />
# pacman -Syu --cachedir /tmp/pacman_pkg<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try {{Pkg|pacredir}}, [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{Pkg|shfs-utils}}, {{Pkg|sshfs}}, {{Pkg|curlftpfs}}, {{Pkg|samba}} or {{Pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Warning|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. Pacman expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{Bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via the rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture-dependent sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy package requests to official upstream mirrors and cache the results to the local disk. All subsequent requests for that package will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of computers. <br />
<br />
In this example, the cache server will run at {{ic|<nowiki>http://cache.domain.example:8080/</nowiki>}} and store the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Install [[nginx]] on the computer that is going to host the cache. Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Use the [https://github.com/nastasie-octavian/nginx_pacman_cache_config/blob/c54eca4776ff162ab492117b80be4df95880d0e2/nginx.conf nginx pacman cache config] as a starting point for {{ic|/etc/nginx/nginx.conf}}. Check that the {{ic|resolver}} directive works for your needs. In the upstream server blocks, configure the {{ic|proxy_pass}} directives with addresses of official mirrors, see examples in the config file about the expected format. Once you are satisfied with the configuration file [[Nginx#Running|start and enable nginx]].<br />
<br />
In order to use the cache each Arch Linux computer (including the one hosting the cache) must have the following line at the top of the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.example:8080/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as the cache directory will continue to grow over time. {{ic|paccache}} (which is provided by {{Pkg|pacman-contrib}}) can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Pacoloco proxy cache server ====<br />
<br />
[https://github.com/anatol/pacoloco Pacoloco] is an easy-to-use proxy cache server for ''pacman'' repositories. It can be installed as {{Pkg|pacoloco}}. Open the configuration file and add ''pacman'' mirrors:<br />
<br />
{{hc|/etc/pacoloco.yaml|<nowiki><br />
port: 9129<br />
repos:<br />
mycopy:<br />
urls:<br />
- http://mirror.lty.me/archlinux<br />
- http://mirrors.kernel.org/archlinux<br />
</nowiki>}}<br />
<br />
[[Restart]] {{ic|pacoloco.service}} and the proxy repository will be available at {{ic|http://<myserver>:9129/repo/mycopy}}.<br />
<br />
==== Flexo proxy cache server ====<br />
<br />
[https://github.com/nroi/flexo Flexo] is yet another proxy cache server for ''pacman'' repositories. Flexo is available as {{AUR|flexo-git}}. Once installed, [[start]] the {{ic|flexo.service}} unit.<br />
<br />
Flexo runs on port {{ic|7878}} by default. Enter {{ic|1=Server = http://''myserver'':7878/$repo/os/$arch}} to the top of your {{ic|/etc/pacman.d/mirrorlist}} so that ''pacman'' downloads packages via Flexo.<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Syncthing]] or [[Resilio Sync]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use {{AUR|fakepkg}}. Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of all the explicitly installed packages can be useful, to backup a system for example or speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|<br />
* With option {{ic|-t}}, the packages already required by other explicitly installed packages are not mentioned. If reinstalling from this list they will be installed but as dependencies only.<br />
* With option {{ic|-n}}, foreign packages (e.g. from [[AUR]]) would be omitted from the list.<br />
* Use {{ic|comm -13 <(pacman -Qqdt {{!}} sort) <(pacman -Qqdtt {{!}} sort) > optdeplist.txt}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
* Use {{ic|pacman -Qqem > foreignpkglist.txt}} to create the list of AUR and other foreign packages that have been explicitly installed.}}<br />
<br />
To keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/pkglist.txt'<br />
<br />
=== Install packages from a list ===<br />
<br />
To install packages from a previously saved list of packages, while not reinstalling previously installed packages that are already up-to-date, run:<br />
<br />
# pacman -S --needed - < pkglist.txt<br />
<br />
However, it is likely foreign packages such as from the AUR or installed locally are present in the list. To filter out from the list the foreign packages, the previous command line can be enriched as follows:<br />
<br />
# pacman -S --needed $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
Eventually, to make sure the installed packages of your system match the list and remove all the packages that are not mentioned in it:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qqn | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qqm}}.<br />
<br />
Pacman preserves the [[installation reason]] by default.<br />
<br />
{{Warning|To force all packages to be overwritten, use {{ic|1=--overwrite=*}}, though this should be an absolute last resort. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ bsdtar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{Pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
=== Installing only content in required languages ===<br />
<br />
Many packages attempt to install documentation and translations in several languages. Some programs are designed to remove such unnecessary files, such as {{AUR|localepurge}}, which runs after a package is installed to delete the unneeded locale files. A more direct approach is provided through the {{ic|NoExtract}} directive in {{ic|pacman.conf}}, which prevent these files from ever being installed.<br />
<br />
{{Warning|1=Some users noted that removing locales has resulted in [[Special:Permalink/460285#Dangerous NoExtract example|unintended consequences]], even under [https://bbs.archlinux.org/viewtopic.php?id=250846 Xorg].}}<br />
<br />
The example below installs English (US) files, or none at all:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
NoExtract = usr/share/help/* !usr/share/help/C/*<br />
NoExtract = usr/share/gtk-doc/html/*<br />
NoExtract = usr/share/locale/* usr/share/X11/locale/*/* usr/share/i18n/locales/* opt/google/chrome/locales/* !usr/share/X11/locale/C/*<br />
NoExtract = !*locale*/en*/* !usr/share/*locale*/locale.*<br />
NoExtract = !usr/share/*locales/en_?? !usr/share/*locales/i18n* !usr/share/*locales/iso*<br />
NoExtract = usr/share/i18n/charmaps/* !usr/share/i18n/charmaps/UTF-8.gz<br />
NoExtract = !usr/share/*locales/trans*<br />
NoExtract = usr/share/man/* !usr/share/man/man*<br />
NoExtract = usr/share/vim/vim*/lang/*<br />
NoExtract = usr/lib/libreoffice/help/en-US/*<br />
NoExtract = usr/share/kbd/locale/*<br />
NoExtract = usr/share/*/translations/*.qm usr/share/qt/translations/*.pak !*/en-US.pak # Qt apps<br />
NoExtract = usr/share/*/locales/*.pak opt/*/locales/*.pak usr/lib/*/locales/*.pak !*/en-US.pak # Electron apps<br />
NoExtract = opt/onlyoffice/desktopeditors/dictionaries/* !opt/onlyoffice/desktopeditors/dictionaries/en_US/*<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/locale/* !*/en.json<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/resources/help/* !*/help/en/*<br />
NoExtract = opt/onlyoffice/desktopeditors/converter/empty/*/*<br />
NoExtract = usr/share/ibus/dicts/emoji-*.dict !usr/share/ibus/dicts/emoji-en.dict<br />
}}<br />
<br />
== Performance ==<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
Pacman's speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki/>'s built-in file downloader, or by [[pacman#Enabling parallel downloads|enabling parallel downloads]].<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki/>'s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget --passive-ftp --show-progress -c -q -N %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}).<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki/>'s XferCommand will '''not''' result in parallel downloads of multiple packages. Pacman invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using pacman with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See {{man|1|aria2c|OPTIONS}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
* {{ic|saldl}}: {{ic|1=XferCommand = /usr/bin/saldl -c6 -l4 -s2m -o %o %u}} (please read the [https://saldl.github.io documentation on the project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}<br />
* {{App|Pacmatic|Pacman wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|https://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|pkgtop|Interactive package manager and resource monitor designed for the GNU/Linux.|https://github.com/orhun/pkgtop|{{AUR|pkgtop-git}}}}<br />
* {{App|[[Powerpill]]|Uses parallel and segmented downloading through [[aria2]] and [[Reflector]] to try to speed up downloads for ''pacman''.|https://xyne.archlinux.ca/projects/powerpill/|{{AUR|powerpill}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{Pkg|snap-pac}}}}<br />
* {{App|vrms-arch|A virtual Richard M. Stallman to tell you which non-free packages are installed.|https://github.com/orospakr/vrms-arch|{{AUR|vrms-arch-git}}}}<br />
<br />
=== Graphical ===<br />
<br />
{{Warning|PackageKit opens up system permissions by default, and is otherwise not recommended for general usage. See {{Bug|50459}} and {{Bug|57943}}.}}<br />
<br />
* {{App|Apper|Qt 5 application and package manager using PackageKit written in C++. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://userbase.kde.org/Apper|{{Pkg|apper}}}}<br />
* {{App|Deepin App Store|Third party app store for DDE built with DTK, using PackageKit. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://github.com/dekzi/dde-store|{{Pkg|deepin-store}}}}<br />
* {{App|Discover|Qt 5 application manager using PackageKit written in C++/QML. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://userbase.kde.org/Discover|{{Pkg|discover}}}}<br />
* {{App|GNOME PackageKit|GTK 3 package manager using PackageKit written in C.|https://freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|GTK 3 application manager using PackageKit written in C. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://wiki.gnome.org/Apps/Software|{{Pkg|gnome-software}}}}<br />
* {{App|pcurses|Curses TUI ''pacman'' wrapper written in C++.|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Tk pacman wrapper written in Tcl.|https://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=690303Pacman/Tips and tricks2021-08-02T01:55:58Z<p>Thiagowfx: /* Not in a specified group, repository or meta package */ move tip to be the last item in subsection</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[de:Pacman-Tipps]]<br />
[[es:Pacman (Español)/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Pacman (Français)/Tips and tricks]]<br />
[[it:Pacman (Italiano)/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman (Português)/Tips and tricks]]<br />
[[ru:Pacman (Русский)/Tips and tricks]]<br />
[[zh-hans:Pacman (简体中文)/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with ''pacman'' 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
==== With version ====<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all packages in the [[package group]] named {{ic|''group''}}: {{ic|pacman -Sg ''group''}}<br />
* List all foreign packages (typically manually downloaded and installed or packages removed from the repositories): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format (needs {{Pkg|expac}}): {{ic|expac -s "%-30n %v" ''regex''}}.<br />
<br />
==== With size ====<br />
<br />
Figuring out which packages are largest can be useful when trying to free space on your hard drive. There are two options here: get the size of individual packages, or get the size of packages and their dependencies.<br />
<br />
===== Individual packages =====<br />
<br />
The following command will list all installed packages and their individual sizes:<br />
<br />
$ LC_ALL=C pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4$5, name}' | sort -h<br />
<br />
===== Packages and dependencies =====<br />
<br />
To list package sizes with their dependencies,<br />
<br />
* Install {{Pkg|expac}} and run {{ic|expac -H M '%m\t%n' {{!}} sort -h}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in the [[meta package]] {{Pkg|base}} nor [[package group]] {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort | uniq)) | sort -n<br />
<br />
To list the packages marked for upgrade with their download size<br />
<br />
$ expac -S -H M '%k\t%n' $(pacman -Qqu) | sort -sh<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group, repository or meta package ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].<br />
}}<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} [[meta package]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <(expac -l '\n' '%E' base | sort)<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} meta package or {{Grp|base-devel}} [[package group]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Pkg|base}} meta package or {{Grp|base-devel}} package group:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -H M '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the {{Pkg|base}} meta package:<br />
<br />
<nowiki>$ comm -23 <(curl https://gitlab.archlinux.org/archlinux/archiso/-/raw/master/configs/releng/packages.x86_64) <(expac -l '\n' '%E' base | sort)</nowiki><br />
<br />
{{Tip|Alternatively, use {{ic|combine}} (instead of {{ic|comm}}) from the {{Pkg|moreutils}} package which has a syntax that is easier to remember. See {{man|1|combine}}.}}<br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | grep -Ee '-(bzr|cvs|darcs|git|hg|svn)$'<br />
<br />
=== Browsing packages ===<br />
<br />
To browse all installed packages with an instant preview of each package:<br />
<br />
$ pacman -Qq | fzf --preview 'pacman -Qil {}' --layout=reverse --bind 'enter:execute(pacman -Qil {} | less)'<br />
<br />
This uses [[fzf]] to present a two-pane view listing all packages with package info shown on the right.<br />
<br />
Enter letters to filter the list of packages; use arrow keys (or {{ic|Ctrl-j}}/{{ic|Ctrl-k}}) to navigate; press {{ic|Enter}} to see package info under ''less''.<br />
<br />
To browse all packages currently known to ''pacman'' (both installed and not yet installed) in a similar way, using fzf, use:<br />
<br />
$ pacman -Slq | fzf --preview 'pacman -Si {}' --layout=reverse<br />
<br />
The navigational keybindings are the same, although Enter will not work in the same way.<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs -r du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up.<br />
<br />
One method is to use {{ic|pacreport --unowned-files}} as the root user from {{Pkg|pacutils}} which will list unowned files among other details.<br />
<br />
Another is to list all files of interest and check them against ''pacman'':<br />
<br />
# find /etc /usr /opt /var | LC_ALL=C pacman -Qqo - 2>&1 >&- >/dev/null | cut -d ' ' -f 5-<br />
<br />
{{Tip|The {{Pkg|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output.}}<br />
<br />
=== Tracking unowned files created by packages ===<br />
<br />
Most systems will slowly collect several [http://ftp.rpm.org/max-rpm/s1-rpm-inside-files-list-directives.html#S3-RPM-INSIDE-FLIST-GHOST-DIRECTIVE ghost] files such as state files, logs, indexes, etc. through the course of usual operation.<br />
<br />
{{ic|pacreport}} from {{Pkg|pacutils}} can be used to track these files and their associations via {{ic|/etc/pacreport.conf}} (see {{man|1|pacreport|FILES}}).<br />
<br />
An example may look something like this (abridged):<br />
<br />
{{hc|/etc/pacreport.conf|2=<br />
[Options]<br />
IgnoreUnowned = usr/share/applications/mimeinfo.cache<br />
<br />
[PkgIgnoreUnowned]<br />
alsa-utils = var/lib/alsa/asound.state<br />
bluez = var/lib/bluetooth<br />
ca-certificates = etc/ca-certificates/trust-source/*<br />
dbus = var/lib/dbus/machine-id<br />
glibc = etc/ld.so.cache<br />
grub = boot/grub/*<br />
linux = boot/initramfs-linux.img<br />
pacman = var/lib/pacman/local<br />
update-mime-database = usr/share/mime/magic<br />
}}<br />
<br />
Then, when using {{ic|pacreport --unowned-files}} as the root user, any unowned files will be listed if the associated package is no longer installed (or if any new files have been created).<br />
<br />
Additionally, [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) allows tracking modified and orphaned files using a configuration script.<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Qtdq | pacman -Rns -<br />
<br />
If no orphans were found, the output is {{ic|error: argument '-' specified with empty stdin}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but essential packages ===<br />
<br />
If it is ever necessary to remove all packages except the essentials packages, one method is to set the installation reason of the non-essential ones as dependency and then remove all unnecessary dependencies.<br />
<br />
First, for all the packages installed "as explicitly", change their installation reason to "as dependency":<br />
<br />
# pacman -D --asdeps $(pacman -Qqe)<br />
<br />
Then, change the installation reason to "as explicitly" of only the essential packages, those you '''do not''' want to remove, in order to avoid targeting them:<br />
<br />
# pacman -D --asexplicit base linux linux-firmware<br />
<br />
{{Note|<br />
* Additional packages can be added to the above command in order to avoid being removed. See [[Installation guide#Install essential packages]] for more info on other packages that may be necessary for a fully functional base system.<br />
* This will also select the bootloader's package for removal. The system should still be bootable, but the boot parameters might not be changeable without it.<br />
}}<br />
<br />
Finally, follow the instructions in [[#Removing unused packages (orphans)]] to remove all packages that have installation reason "as dependency".<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ LC_ALL=C pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
{{Accuracy|What is the connection of this section to [[System backup]]? Listing modified "backup files" does not show files which are not tracked by ''pacman''.|section=Warning about listing changed backup files}}<br />
<br />
If you want to back up your system configuration files, you could copy all files in {{ic|/etc/}} but usually you are only interested in the files that you have changed. Modified [[Pacnew and Pacsave files#Package backup files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows about, not only backup files.}}<br />
<br />
=== Back up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw --cachedir . base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Pacman, which will reference the host installation by default, will not properly resolve and download existing dependencies. In cases where all packages and dependencies are wanted, it is recommended to create a temporary blank DB and reference it with {{ic|--dbpath}}:<br />
<br />
# mkdir /tmp/blankdb<br />
# pacman -Syw --cachedir . --dbpath /tmp/blankdb base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. <br />
A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', ''.tar.zst'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.<br />
<br />
To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the {{man|8|vercmp}} ordering used by ''pacman''.}}<br />
<br />
If you are looking to support multiple architectures then precautions should be taken to prevent errors from occurring. Each architecture should have its own directory tree:<br />
<br />
{{hc|$ tree ~/customrepo/ {{!}} sed "s/$(uname -m)/<arch>/g"|<br />
/home/archie/customrepo/<br />
└── <arch><br />
├── customrepo.db -> customrepo.db.tar.xz<br />
├── customrepo.db.tar.xz<br />
├── customrepo.files -> customrepo.files.tar.xz<br />
├── customrepo.files.tar.xz<br />
└── personal-website-git-b99cce0-1-<arch>.pkg.tar.xz<br />
<br />
1 directory, 5 files<br />
}}<br />
<br />
The ''repo-add'' executable checks if the package is appropriate. If this is not the case you will be running into error messages similar to this:<br />
<br />
==> ERROR: '/home/archie/customrepo/<arch>/foo-<arch>.pkg.tar.xz' does not have a valid database archive extension.<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
{{Merge|Package_Proxy_Cache|Same topic}}<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver, e.g. {{Pkg|darkhttpd}}, which other computers can use as a first mirror:<br />
<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
If you are already running a web server for some other purpose, you might wish to reuse that as your local repo server instead of darkhttpd. For example, if you already serve a site with [[nginx]], you can add an nginx server block listening on port 8080:<br />
<br />
{{hc|/etc/nginx/nginx.conf|<br />
server {<br />
listen 8080;<br />
root /var/cache/pacman/pkg;<br />
server_name myarchrepo.localdomain;<br />
try_files $uri $uri/;<br />
}<br />
}}<br />
<br />
Remember to restart nginx after making this change.<br />
<br />
Whichever web server you use, remember to open port 8080 to local traffic (and you probably want to deny anything not local). For example, if using [[iptables]], add {{ic|-s 192.168.0.0/16 -p tcp --dport 8080 -j ACCEPT}} to your ruleset (adjust for your LAN subnet if necessary).<br />
<br />
==== Overlay mount of read-only cache ====<br />
<br />
It is possible to use one machine on a local network as a read-only package cache by [[Overlay_filesystem|overlay mounting]] its {{ic|/var/cache/pacman/pkg}} directory. Such a configuration is advantageous if this server has installed on it a reasonably comprehensive selection of up-to-date packages which are also used by other boxes. This is useful for maintaining a number of machines at the end of a low bandwidth upstream connection.<br />
<br />
As an example, to use this method:<br />
<br />
# mkdir /tmp/remote_pkg /mnt/workdir_pkg /tmp/pacman_pkg<br />
# sshfs <remote_username>@<remote_pkgcache_addr>:/var/cache/pacman/pkg /tmp/remote_pkg -C<br />
# mount -t overlay overlay -o lowerdir=/tmp/remote_pkg,upperdir=/var/cache/pacman/pkg,workdir=/mnt/workdir_pkg /tmp/pacman_pkg<br />
<br />
[[Overlay_filesystem#Usage|Note concerning overlay]]: The working directory must be an empty directory on the same mounted device as the upper directory.<br />
<br />
After this, run ''pacman'' using the option {{ic|--cachedir /tmp/pacman_pkg}}, e.g.:<br />
<br />
# pacman -Syu --cachedir /tmp/pacman_pkg<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try {{Pkg|pacredir}}, [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{Pkg|shfs-utils}}, {{Pkg|sshfs}}, {{Pkg|curlftpfs}}, {{Pkg|samba}} or {{Pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Warning|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. Pacman expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{Bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via the rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture-dependent sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy package requests to official upstream mirrors and cache the results to the local disk. All subsequent requests for that package will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of computers. <br />
<br />
In this example, the cache server will run at {{ic|<nowiki>http://cache.domain.example:8080/</nowiki>}} and store the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Install [[nginx]] on the computer that is going to host the cache. Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Use the [https://github.com/nastasie-octavian/nginx_pacman_cache_config/blob/c54eca4776ff162ab492117b80be4df95880d0e2/nginx.conf nginx pacman cache config] as a starting point for {{ic|/etc/nginx/nginx.conf}}. Check that the {{ic|resolver}} directive works for your needs. In the upstream server blocks, configure the {{ic|proxy_pass}} directives with addresses of official mirrors, see examples in the config file about the expected format. Once you are satisfied with the configuration file [[Nginx#Running|start and enable nginx]].<br />
<br />
In order to use the cache each Arch Linux computer (including the one hosting the cache) must have the following line at the top of the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.example:8080/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as the cache directory will continue to grow over time. {{ic|paccache}} (which is provided by {{Pkg|pacman-contrib}}) can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Pacoloco proxy cache server ====<br />
<br />
[https://github.com/anatol/pacoloco Pacoloco] is an easy-to-use proxy cache server for ''pacman'' repositories. It can be installed as {{Pkg|pacoloco}}. Open the configuration file and add ''pacman'' mirrors:<br />
<br />
{{hc|/etc/pacoloco.yaml|<nowiki><br />
port: 9129<br />
repos:<br />
mycopy:<br />
urls:<br />
- http://mirror.lty.me/archlinux<br />
- http://mirrors.kernel.org/archlinux<br />
</nowiki>}}<br />
<br />
[[Restart]] {{ic|pacoloco.service}} and the proxy repository will be available at {{ic|http://<myserver>:9129/repo/mycopy}}.<br />
<br />
==== Flexo proxy cache server ====<br />
<br />
[https://github.com/nroi/flexo Flexo] is yet another proxy cache server for ''pacman'' repositories. Flexo is available as {{AUR|flexo-git}}. Once installed, [[start]] the {{ic|flexo.service}} unit.<br />
<br />
Flexo runs on port {{ic|7878}} by default. Enter {{ic|1=Server = http://''myserver'':7878/$repo/os/$arch}} to the top of your {{ic|/etc/pacman.d/mirrorlist}} so that ''pacman'' downloads packages via Flexo.<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Syncthing]] or [[Resilio Sync]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use {{AUR|fakepkg}}. Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of all the explicitly installed packages can be useful, to backup a system for example or speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|<br />
* With option {{ic|-t}}, the packages already required by other explicitly installed packages are not mentioned. If reinstalling from this list they will be installed but as dependencies only.<br />
* With option {{ic|-n}}, foreign packages (e.g. from [[AUR]]) would be omitted from the list.<br />
* Use {{ic|comm -13 <(pacman -Qqdt {{!}} sort) <(pacman -Qqdtt {{!}} sort) > optdeplist.txt}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
* Use {{ic|pacman -Qqem > foreignpkglist.txt}} to create the list of AUR and other foreign packages that have been explicitly installed.}}<br />
<br />
To keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/pkglist.txt'<br />
<br />
=== Install packages from a list ===<br />
<br />
To install packages from a previously saved list of packages, while not reinstalling previously installed packages that are already up-to-date, run:<br />
<br />
# pacman -S --needed - < pkglist.txt<br />
<br />
However, it is likely foreign packages such as from the AUR or installed locally are present in the list. To filter out from the list the foreign packages, the previous command line can be enriched as follows:<br />
<br />
# pacman -S --needed $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
Eventually, to make sure the installed packages of your system match the list and remove all the packages that are not mentioned in it:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qqn | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qqm}}.<br />
<br />
Pacman preserves the [[installation reason]] by default.<br />
<br />
{{Warning|To force all packages to be overwritten, use {{ic|1=--overwrite=*}}, though this should be an absolute last resort. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ bsdtar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{Pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
=== Installing only content in required languages ===<br />
<br />
Many packages attempt to install documentation and translations in several languages. Some programs are designed to remove such unnecessary files, such as {{AUR|localepurge}}, which runs after a package is installed to delete the unneeded locale files. A more direct approach is provided through the {{ic|NoExtract}} directive in {{ic|pacman.conf}}, which prevent these files from ever being installed.<br />
<br />
{{Warning|1=Some users noted that removing locales has resulted in [[Special:Permalink/460285#Dangerous NoExtract example|unintended consequences]], even under [https://bbs.archlinux.org/viewtopic.php?id=250846 Xorg].}}<br />
<br />
The example below installs English (US) files, or none at all:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
NoExtract = usr/share/help/* !usr/share/help/C/*<br />
NoExtract = usr/share/gtk-doc/html/*<br />
NoExtract = usr/share/locale/* usr/share/X11/locale/*/* usr/share/i18n/locales/* opt/google/chrome/locales/* !usr/share/X11/locale/C/*<br />
NoExtract = !*locale*/en*/* !usr/share/*locale*/locale.*<br />
NoExtract = !usr/share/*locales/en_?? !usr/share/*locales/i18n* !usr/share/*locales/iso*<br />
NoExtract = usr/share/i18n/charmaps/* !usr/share/i18n/charmaps/UTF-8.gz<br />
NoExtract = !usr/share/*locales/trans*<br />
NoExtract = usr/share/man/* !usr/share/man/man*<br />
NoExtract = usr/share/vim/vim*/lang/*<br />
NoExtract = usr/lib/libreoffice/help/en-US/*<br />
NoExtract = usr/share/kbd/locale/*<br />
NoExtract = usr/share/*/translations/*.qm usr/share/qt/translations/*.pak !*/en-US.pak # Qt apps<br />
NoExtract = usr/share/*/locales/*.pak opt/*/locales/*.pak usr/lib/*/locales/*.pak !*/en-US.pak # Electron apps<br />
NoExtract = opt/onlyoffice/desktopeditors/dictionaries/* !opt/onlyoffice/desktopeditors/dictionaries/en_US/*<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/locale/* !*/en.json<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/resources/help/* !*/help/en/*<br />
NoExtract = opt/onlyoffice/desktopeditors/converter/empty/*/*<br />
NoExtract = usr/share/ibus/dicts/emoji-*.dict !usr/share/ibus/dicts/emoji-en.dict<br />
}}<br />
<br />
== Performance ==<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
Pacman's speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki/>'s built-in file downloader, or by [[pacman#Enabling parallel downloads|enabling parallel downloads]].<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki/>'s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget --passive-ftp --show-progress -c -q -N %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}).<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki/>'s XferCommand will '''not''' result in parallel downloads of multiple packages. Pacman invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using pacman with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See {{man|1|aria2c|OPTIONS}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
* {{ic|saldl}}: {{ic|1=XferCommand = /usr/bin/saldl -c6 -l4 -s2m -o %o %u}} (please read the [https://saldl.github.io documentation on the project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}<br />
* {{App|Pacmatic|Pacman wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|https://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|pkgtop|Interactive package manager and resource monitor designed for the GNU/Linux.|https://github.com/orhun/pkgtop|{{AUR|pkgtop-git}}}}<br />
* {{App|[[Powerpill]]|Uses parallel and segmented downloading through [[aria2]] and [[Reflector]] to try to speed up downloads for ''pacman''.|https://xyne.archlinux.ca/projects/powerpill/|{{AUR|powerpill}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{Pkg|snap-pac}}}}<br />
* {{App|vrms-arch|A virtual Richard M. Stallman to tell you which non-free packages are installed.|https://github.com/orospakr/vrms-arch|{{AUR|vrms-arch-git}}}}<br />
<br />
=== Graphical ===<br />
<br />
{{Warning|PackageKit opens up system permissions by default, and is otherwise not recommended for general usage. See {{Bug|50459}} and {{Bug|57943}}.}}<br />
<br />
* {{App|Apper|Qt 5 application and package manager using PackageKit written in C++. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://userbase.kde.org/Apper|{{Pkg|apper}}}}<br />
* {{App|Deepin App Store|Third party app store for DDE built with DTK, using PackageKit. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://github.com/dekzi/dde-store|{{Pkg|deepin-store}}}}<br />
* {{App|Discover|Qt 5 application manager using PackageKit written in C++/QML. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://userbase.kde.org/Discover|{{Pkg|discover}}}}<br />
* {{App|GNOME PackageKit|GTK 3 package manager using PackageKit written in C.|https://freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|GTK 3 application manager using PackageKit written in C. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://wiki.gnome.org/Apps/Software|{{Pkg|gnome-software}}}}<br />
* {{App|pcurses|Curses TUI ''pacman'' wrapper written in C++.|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Tk pacman wrapper written in Tcl.|https://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=690302Pacman/Tips and tricks2021-08-02T01:55:07Z<p>Thiagowfx: /* Not in a specified group, repository or meta package */ add tip about combine instead of comm</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[de:Pacman-Tipps]]<br />
[[es:Pacman (Español)/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Pacman (Français)/Tips and tricks]]<br />
[[it:Pacman (Italiano)/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman (Português)/Tips and tricks]]<br />
[[ru:Pacman (Русский)/Tips and tricks]]<br />
[[zh-hans:Pacman (简体中文)/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with ''pacman'' 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
==== With version ====<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all packages in the [[package group]] named {{ic|''group''}}: {{ic|pacman -Sg ''group''}}<br />
* List all foreign packages (typically manually downloaded and installed or packages removed from the repositories): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format (needs {{Pkg|expac}}): {{ic|expac -s "%-30n %v" ''regex''}}.<br />
<br />
==== With size ====<br />
<br />
Figuring out which packages are largest can be useful when trying to free space on your hard drive. There are two options here: get the size of individual packages, or get the size of packages and their dependencies.<br />
<br />
===== Individual packages =====<br />
<br />
The following command will list all installed packages and their individual sizes:<br />
<br />
$ LC_ALL=C pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4$5, name}' | sort -h<br />
<br />
===== Packages and dependencies =====<br />
<br />
To list package sizes with their dependencies,<br />
<br />
* Install {{Pkg|expac}} and run {{ic|expac -H M '%m\t%n' {{!}} sort -h}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in the [[meta package]] {{Pkg|base}} nor [[package group]] {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort | uniq)) | sort -n<br />
<br />
To list the packages marked for upgrade with their download size<br />
<br />
$ expac -S -H M '%k\t%n' $(pacman -Qqu) | sort -sh<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group, repository or meta package ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].<br />
}}<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} [[meta package]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <(expac -l '\n' '%E' base | sort)<br />
<br />
List explicitly installed packages not in the {{Pkg|base}} meta package or {{Grp|base-devel}} [[package group]]:<br />
<br />
$ comm -23 <(pacman -Qqe | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Pkg|base}} meta package or {{Grp|base-devel}} package group:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -H M '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg base-devel; expac -l '\n' '%E' base; } | sort -u))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)<br />
<br />
{{Tip|Alternatively, use {{ic|combine}} (instead of {{ic|comm}}) from the {{Pkg|moreutils}} package which has a syntax that is easier to remember. See {{man|1|combine}}.}}<br />
<br />
List all packages on the Arch Linux ISO that are not in the {{Pkg|base}} meta package:<br />
<br />
<nowiki>$ comm -23 <(curl https://gitlab.archlinux.org/archlinux/archiso/-/raw/master/configs/releng/packages.x86_64) <(expac -l '\n' '%E' base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | grep -Ee '-(bzr|cvs|darcs|git|hg|svn)$'<br />
<br />
=== Browsing packages ===<br />
<br />
To browse all installed packages with an instant preview of each package:<br />
<br />
$ pacman -Qq | fzf --preview 'pacman -Qil {}' --layout=reverse --bind 'enter:execute(pacman -Qil {} | less)'<br />
<br />
This uses [[fzf]] to present a two-pane view listing all packages with package info shown on the right.<br />
<br />
Enter letters to filter the list of packages; use arrow keys (or {{ic|Ctrl-j}}/{{ic|Ctrl-k}}) to navigate; press {{ic|Enter}} to see package info under ''less''.<br />
<br />
To browse all packages currently known to ''pacman'' (both installed and not yet installed) in a similar way, using fzf, use:<br />
<br />
$ pacman -Slq | fzf --preview 'pacman -Si {}' --layout=reverse<br />
<br />
The navigational keybindings are the same, although Enter will not work in the same way.<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs -r du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up.<br />
<br />
One method is to use {{ic|pacreport --unowned-files}} as the root user from {{Pkg|pacutils}} which will list unowned files among other details.<br />
<br />
Another is to list all files of interest and check them against ''pacman'':<br />
<br />
# find /etc /usr /opt /var | LC_ALL=C pacman -Qqo - 2>&1 >&- >/dev/null | cut -d ' ' -f 5-<br />
<br />
{{Tip|The {{Pkg|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output.}}<br />
<br />
=== Tracking unowned files created by packages ===<br />
<br />
Most systems will slowly collect several [http://ftp.rpm.org/max-rpm/s1-rpm-inside-files-list-directives.html#S3-RPM-INSIDE-FLIST-GHOST-DIRECTIVE ghost] files such as state files, logs, indexes, etc. through the course of usual operation.<br />
<br />
{{ic|pacreport}} from {{Pkg|pacutils}} can be used to track these files and their associations via {{ic|/etc/pacreport.conf}} (see {{man|1|pacreport|FILES}}).<br />
<br />
An example may look something like this (abridged):<br />
<br />
{{hc|/etc/pacreport.conf|2=<br />
[Options]<br />
IgnoreUnowned = usr/share/applications/mimeinfo.cache<br />
<br />
[PkgIgnoreUnowned]<br />
alsa-utils = var/lib/alsa/asound.state<br />
bluez = var/lib/bluetooth<br />
ca-certificates = etc/ca-certificates/trust-source/*<br />
dbus = var/lib/dbus/machine-id<br />
glibc = etc/ld.so.cache<br />
grub = boot/grub/*<br />
linux = boot/initramfs-linux.img<br />
pacman = var/lib/pacman/local<br />
update-mime-database = usr/share/mime/magic<br />
}}<br />
<br />
Then, when using {{ic|pacreport --unowned-files}} as the root user, any unowned files will be listed if the associated package is no longer installed (or if any new files have been created).<br />
<br />
Additionally, [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) allows tracking modified and orphaned files using a configuration script.<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Qtdq | pacman -Rns -<br />
<br />
If no orphans were found, the output is {{ic|error: argument '-' specified with empty stdin}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but essential packages ===<br />
<br />
If it is ever necessary to remove all packages except the essentials packages, one method is to set the installation reason of the non-essential ones as dependency and then remove all unnecessary dependencies.<br />
<br />
First, for all the packages installed "as explicitly", change their installation reason to "as dependency":<br />
<br />
# pacman -D --asdeps $(pacman -Qqe)<br />
<br />
Then, change the installation reason to "as explicitly" of only the essential packages, those you '''do not''' want to remove, in order to avoid targeting them:<br />
<br />
# pacman -D --asexplicit base linux linux-firmware<br />
<br />
{{Note|<br />
* Additional packages can be added to the above command in order to avoid being removed. See [[Installation guide#Install essential packages]] for more info on other packages that may be necessary for a fully functional base system.<br />
* This will also select the bootloader's package for removal. The system should still be bootable, but the boot parameters might not be changeable without it.<br />
}}<br />
<br />
Finally, follow the instructions in [[#Removing unused packages (orphans)]] to remove all packages that have installation reason "as dependency".<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ LC_ALL=C pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
{{Accuracy|What is the connection of this section to [[System backup]]? Listing modified "backup files" does not show files which are not tracked by ''pacman''.|section=Warning about listing changed backup files}}<br />
<br />
If you want to back up your system configuration files, you could copy all files in {{ic|/etc/}} but usually you are only interested in the files that you have changed. Modified [[Pacnew and Pacsave files#Package backup files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows about, not only backup files.}}<br />
<br />
=== Back up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw --cachedir . base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Pacman, which will reference the host installation by default, will not properly resolve and download existing dependencies. In cases where all packages and dependencies are wanted, it is recommended to create a temporary blank DB and reference it with {{ic|--dbpath}}:<br />
<br />
# mkdir /tmp/blankdb<br />
# pacman -Syw --cachedir . --dbpath /tmp/blankdb base base-devel grub-bios xorg gimp<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. <br />
A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', ''.tar.zst'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.<br />
<br />
To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the {{man|8|vercmp}} ordering used by ''pacman''.}}<br />
<br />
If you are looking to support multiple architectures then precautions should be taken to prevent errors from occurring. Each architecture should have its own directory tree:<br />
<br />
{{hc|$ tree ~/customrepo/ {{!}} sed "s/$(uname -m)/<arch>/g"|<br />
/home/archie/customrepo/<br />
└── <arch><br />
├── customrepo.db -> customrepo.db.tar.xz<br />
├── customrepo.db.tar.xz<br />
├── customrepo.files -> customrepo.files.tar.xz<br />
├── customrepo.files.tar.xz<br />
└── personal-website-git-b99cce0-1-<arch>.pkg.tar.xz<br />
<br />
1 directory, 5 files<br />
}}<br />
<br />
The ''repo-add'' executable checks if the package is appropriate. If this is not the case you will be running into error messages similar to this:<br />
<br />
==> ERROR: '/home/archie/customrepo/<arch>/foo-<arch>.pkg.tar.xz' does not have a valid database archive extension.<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
{{Merge|Package_Proxy_Cache|Same topic}}<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver, e.g. {{Pkg|darkhttpd}}, which other computers can use as a first mirror:<br />
<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
If you are already running a web server for some other purpose, you might wish to reuse that as your local repo server instead of darkhttpd. For example, if you already serve a site with [[nginx]], you can add an nginx server block listening on port 8080:<br />
<br />
{{hc|/etc/nginx/nginx.conf|<br />
server {<br />
listen 8080;<br />
root /var/cache/pacman/pkg;<br />
server_name myarchrepo.localdomain;<br />
try_files $uri $uri/;<br />
}<br />
}}<br />
<br />
Remember to restart nginx after making this change.<br />
<br />
Whichever web server you use, remember to open port 8080 to local traffic (and you probably want to deny anything not local). For example, if using [[iptables]], add {{ic|-s 192.168.0.0/16 -p tcp --dport 8080 -j ACCEPT}} to your ruleset (adjust for your LAN subnet if necessary).<br />
<br />
==== Overlay mount of read-only cache ====<br />
<br />
It is possible to use one machine on a local network as a read-only package cache by [[Overlay_filesystem|overlay mounting]] its {{ic|/var/cache/pacman/pkg}} directory. Such a configuration is advantageous if this server has installed on it a reasonably comprehensive selection of up-to-date packages which are also used by other boxes. This is useful for maintaining a number of machines at the end of a low bandwidth upstream connection.<br />
<br />
As an example, to use this method:<br />
<br />
# mkdir /tmp/remote_pkg /mnt/workdir_pkg /tmp/pacman_pkg<br />
# sshfs <remote_username>@<remote_pkgcache_addr>:/var/cache/pacman/pkg /tmp/remote_pkg -C<br />
# mount -t overlay overlay -o lowerdir=/tmp/remote_pkg,upperdir=/var/cache/pacman/pkg,workdir=/mnt/workdir_pkg /tmp/pacman_pkg<br />
<br />
[[Overlay_filesystem#Usage|Note concerning overlay]]: The working directory must be an empty directory on the same mounted device as the upper directory.<br />
<br />
After this, run ''pacman'' using the option {{ic|--cachedir /tmp/pacman_pkg}}, e.g.:<br />
<br />
# pacman -Syu --cachedir /tmp/pacman_pkg<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try {{Pkg|pacredir}}, [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{Pkg|shfs-utils}}, {{Pkg|sshfs}}, {{Pkg|curlftpfs}}, {{Pkg|samba}} or {{Pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Warning|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. Pacman expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{Bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via the rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture-dependent sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy package requests to official upstream mirrors and cache the results to the local disk. All subsequent requests for that package will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of computers. <br />
<br />
In this example, the cache server will run at {{ic|<nowiki>http://cache.domain.example:8080/</nowiki>}} and store the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Install [[nginx]] on the computer that is going to host the cache. Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Use the [https://github.com/nastasie-octavian/nginx_pacman_cache_config/blob/c54eca4776ff162ab492117b80be4df95880d0e2/nginx.conf nginx pacman cache config] as a starting point for {{ic|/etc/nginx/nginx.conf}}. Check that the {{ic|resolver}} directive works for your needs. In the upstream server blocks, configure the {{ic|proxy_pass}} directives with addresses of official mirrors, see examples in the config file about the expected format. Once you are satisfied with the configuration file [[Nginx#Running|start and enable nginx]].<br />
<br />
In order to use the cache each Arch Linux computer (including the one hosting the cache) must have the following line at the top of the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.example:8080/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as the cache directory will continue to grow over time. {{ic|paccache}} (which is provided by {{Pkg|pacman-contrib}}) can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Pacoloco proxy cache server ====<br />
<br />
[https://github.com/anatol/pacoloco Pacoloco] is an easy-to-use proxy cache server for ''pacman'' repositories. It can be installed as {{Pkg|pacoloco}}. Open the configuration file and add ''pacman'' mirrors:<br />
<br />
{{hc|/etc/pacoloco.yaml|<nowiki><br />
port: 9129<br />
repos:<br />
mycopy:<br />
urls:<br />
- http://mirror.lty.me/archlinux<br />
- http://mirrors.kernel.org/archlinux<br />
</nowiki>}}<br />
<br />
[[Restart]] {{ic|pacoloco.service}} and the proxy repository will be available at {{ic|http://<myserver>:9129/repo/mycopy}}.<br />
<br />
==== Flexo proxy cache server ====<br />
<br />
[https://github.com/nroi/flexo Flexo] is yet another proxy cache server for ''pacman'' repositories. Flexo is available as {{AUR|flexo-git}}. Once installed, [[start]] the {{ic|flexo.service}} unit.<br />
<br />
Flexo runs on port {{ic|7878}} by default. Enter {{ic|1=Server = http://''myserver'':7878/$repo/os/$arch}} to the top of your {{ic|/etc/pacman.d/mirrorlist}} so that ''pacman'' downloads packages via Flexo.<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Syncthing]] or [[Resilio Sync]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use {{AUR|fakepkg}}. Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of all the explicitly installed packages can be useful, to backup a system for example or speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|<br />
* With option {{ic|-t}}, the packages already required by other explicitly installed packages are not mentioned. If reinstalling from this list they will be installed but as dependencies only.<br />
* With option {{ic|-n}}, foreign packages (e.g. from [[AUR]]) would be omitted from the list.<br />
* Use {{ic|comm -13 <(pacman -Qqdt {{!}} sort) <(pacman -Qqdtt {{!}} sort) > optdeplist.txt}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
* Use {{ic|pacman -Qqem > foreignpkglist.txt}} to create the list of AUR and other foreign packages that have been explicitly installed.}}<br />
<br />
To keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/pkglist.txt'<br />
<br />
=== Install packages from a list ===<br />
<br />
To install packages from a previously saved list of packages, while not reinstalling previously installed packages that are already up-to-date, run:<br />
<br />
# pacman -S --needed - < pkglist.txt<br />
<br />
However, it is likely foreign packages such as from the AUR or installed locally are present in the list. To filter out from the list the foreign packages, the previous command line can be enriched as follows:<br />
<br />
# pacman -S --needed $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
Eventually, to make sure the installed packages of your system match the list and remove all the packages that are not mentioned in it:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qqn | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qqm}}.<br />
<br />
Pacman preserves the [[installation reason]] by default.<br />
<br />
{{Warning|To force all packages to be overwritten, use {{ic|1=--overwrite=*}}, though this should be an absolute last resort. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ bsdtar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{Pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
=== Installing only content in required languages ===<br />
<br />
Many packages attempt to install documentation and translations in several languages. Some programs are designed to remove such unnecessary files, such as {{AUR|localepurge}}, which runs after a package is installed to delete the unneeded locale files. A more direct approach is provided through the {{ic|NoExtract}} directive in {{ic|pacman.conf}}, which prevent these files from ever being installed.<br />
<br />
{{Warning|1=Some users noted that removing locales has resulted in [[Special:Permalink/460285#Dangerous NoExtract example|unintended consequences]], even under [https://bbs.archlinux.org/viewtopic.php?id=250846 Xorg].}}<br />
<br />
The example below installs English (US) files, or none at all:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
NoExtract = usr/share/help/* !usr/share/help/C/*<br />
NoExtract = usr/share/gtk-doc/html/*<br />
NoExtract = usr/share/locale/* usr/share/X11/locale/*/* usr/share/i18n/locales/* opt/google/chrome/locales/* !usr/share/X11/locale/C/*<br />
NoExtract = !*locale*/en*/* !usr/share/*locale*/locale.*<br />
NoExtract = !usr/share/*locales/en_?? !usr/share/*locales/i18n* !usr/share/*locales/iso*<br />
NoExtract = usr/share/i18n/charmaps/* !usr/share/i18n/charmaps/UTF-8.gz<br />
NoExtract = !usr/share/*locales/trans*<br />
NoExtract = usr/share/man/* !usr/share/man/man*<br />
NoExtract = usr/share/vim/vim*/lang/*<br />
NoExtract = usr/lib/libreoffice/help/en-US/*<br />
NoExtract = usr/share/kbd/locale/*<br />
NoExtract = usr/share/*/translations/*.qm usr/share/qt/translations/*.pak !*/en-US.pak # Qt apps<br />
NoExtract = usr/share/*/locales/*.pak opt/*/locales/*.pak usr/lib/*/locales/*.pak !*/en-US.pak # Electron apps<br />
NoExtract = opt/onlyoffice/desktopeditors/dictionaries/* !opt/onlyoffice/desktopeditors/dictionaries/en_US/*<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/locale/* !*/en.json<br />
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/resources/help/* !*/help/en/*<br />
NoExtract = opt/onlyoffice/desktopeditors/converter/empty/*/*<br />
NoExtract = usr/share/ibus/dicts/emoji-*.dict !usr/share/ibus/dicts/emoji-en.dict<br />
}}<br />
<br />
== Performance ==<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
Pacman's speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki/>'s built-in file downloader, or by [[pacman#Enabling parallel downloads|enabling parallel downloads]].<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki/>'s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget --passive-ftp --show-progress -c -q -N %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}).<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki/>'s XferCommand will '''not''' result in parallel downloads of multiple packages. Pacman invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using pacman with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See {{man|1|aria2c|OPTIONS}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
* {{ic|saldl}}: {{ic|1=XferCommand = /usr/bin/saldl -c6 -l4 -s2m -o %o %u}} (please read the [https://saldl.github.io documentation on the project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}<br />
* {{App|Pacmatic|Pacman wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|https://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|pkgtop|Interactive package manager and resource monitor designed for the GNU/Linux.|https://github.com/orhun/pkgtop|{{AUR|pkgtop-git}}}}<br />
* {{App|[[Powerpill]]|Uses parallel and segmented downloading through [[aria2]] and [[Reflector]] to try to speed up downloads for ''pacman''.|https://xyne.archlinux.ca/projects/powerpill/|{{AUR|powerpill}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{Pkg|snap-pac}}}}<br />
* {{App|vrms-arch|A virtual Richard M. Stallman to tell you which non-free packages are installed.|https://github.com/orospakr/vrms-arch|{{AUR|vrms-arch-git}}}}<br />
<br />
=== Graphical ===<br />
<br />
{{Warning|PackageKit opens up system permissions by default, and is otherwise not recommended for general usage. See {{Bug|50459}} and {{Bug|57943}}.}}<br />
<br />
* {{App|Apper|Qt 5 application and package manager using PackageKit written in C++. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://userbase.kde.org/Apper|{{Pkg|apper}}}}<br />
* {{App|Deepin App Store|Third party app store for DDE built with DTK, using PackageKit. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata].|https://github.com/dekzi/dde-store|{{Pkg|deepin-store}}}}<br />
* {{App|Discover|Qt 5 application manager using PackageKit written in C++/QML. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://userbase.kde.org/Discover|{{Pkg|discover}}}}<br />
* {{App|GNOME PackageKit|GTK 3 package manager using PackageKit written in C.|https://freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|GTK 3 application manager using PackageKit written in C. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. |https://wiki.gnome.org/Apps/Software|{{Pkg|gnome-software}}}}<br />
* {{App|pcurses|Curses TUI ''pacman'' wrapper written in C++.|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|tkPacman|Tk pacman wrapper written in Tcl.|https://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Greetd&diff=690062Greetd2021-08-01T07:54:33Z<p>Thiagowfx: /* tuigreet */ fix heading level</p>
<hr />
<div>[[Category:Display managers]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|Wayland}}<br />
{{Related|Sway}}<br />
{{Related articles end}}<br />
[https://git.sr.ht/~kennylevinsen/greetd greetd] is a minimal, agnostic and flexible [[login manager]] daemon which doesn't make assumptions about what the user wants to launch, should it be console-based or graphical. Any script or program which can be started from the console may be launched by greetd, which makes it particularly suitable for [[Wayland#Compositors|Wayland compositors]]. It can also launch a [[#Greeters|greeter]] to start user sessions, like any other display manager.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{AUR|greetd}} or {{AUR|greetd-git}} packages.<br />
<br />
== Configuration ==<br />
<br />
The default configuration file is {{ic|/etc/greetd/config.toml}}. [[PAM]]-specific options should be set in {{ic|/etc/pam.d/greetd}}.<br />
<br />
=== Greeters ===<br />
<br />
In order to allow user sessions to be started, greetd can launch a greeter. Several greeters are available:<br />
<br />
* {{ic|agreety}}, a text-based greeter similar to [[agetty]] which is provided by the {{AUR|greetd}}/{{AUR|greetd-git}} package.<br />
* [https://git.sr.ht/~kennylevinsen/gtkgreet gtkgreet] (provided by {{AUR|greetd-gtkgreet}}/{{AUR|greetd-gtkgreet-git}}), a [[GTK]] greeter.<br />
* [https://git.sr.ht/~kennylevinsen/wlgreet wlgreet] (provided by by {{AUR|greetd-wlgreet}}/{{AUR|greetd-wlgreet-git}}), a [[Wayland]] greeter.<br />
* [https://git.sr.ht/~kennylevinsen/dlm dlm] (provided by {{AUR|greetd-dlm-git}}), a simple greeter which uses fbdev.<br />
* [https://github.com/apognu/tuigreet tuigreet] (provided by {{AUR|greetd-tuigreet}}), a console UI greeter.<br />
<br />
By default, greeters are run as the {{ic|greeter}} user. This can be changed by editing the {{ic|user}} option in the {{ic|default_session}} section of the configuration file and replacing ''another_user'' with the chosen user:<br />
<br />
...<br />
user = "another_user"<br />
...<br />
<br />
Make sure the [[ownership]] of the {{ic|/etc/greetd}} directory is set accordingly.<br />
<br />
==== agreety ====<br />
<br />
In order to launch a normal console session with agreety, edit the configuration file as follows:<br />
...<br />
[default_session]<br />
command = "agreety --cmd $SHELL"<br />
...<br />
<br />
agreety can launch any arbitrary command once a user logs in. For example, in order to start [[Sway]], replace {{ic|$SHELL}} in the example above with {{ic|sway}}.<br />
<br />
==== gtkgreet ====<br />
<br />
In order to run, gtkgreet needs a compositor. It is recommended to use Sway, but {{pkg|cage}} can also be used. Make sure the compositor you would like to use is [[install]]ed before starting greetd.<br />
If you want to use cage, your {{ic|[default_session]}} section should be:<br />
...<br />
[default_session]<br />
command = "cage gtkgreet"<br />
...<br />
<br />
If you want to use Sway, the greeter must be terminated once the user logs in. For that purpose, a specific configuration file must be created for Sway, for example in {{ic|/etc/greetd/sway-config}}, with the following content:<br />
# `-l` activates layer-shell mode. Notice that `swaymsg exit` will run after gtkgreet.<br />
exec "gtkgreet -l; swaymsg exit"<br />
<br />
bindsym Mod4+shift+e exec swaynag \<br />
-t warning \<br />
-m 'What do you want to do?' \<br />
-b 'Poweroff' 'systemctl poweroff' \<br />
-b 'Reboot' 'systemctl reboot'<br />
<br />
include /etc/sway/config.d/*<br />
<br />
Then, gtkgreeter must be set to start Sway with the configuration file above:<br />
...<br />
[default_session]<br />
command = "sway --config /etc/greetd/sway-config"<br />
...<br />
<br />
In order to specify which login environments can be started by gtkgreet, list them in {{ic|/etc/greetd/environments}}. For example:<br />
sway<br />
bash<br />
<br />
Instead, you can also invoke gtkgreet with the {{ic|-c ''mycommand''}} parameter, replacing ''mycommand'' with the desired program (for example, {{ic|bash}} or {{ic|sway}}) either in {{ic|/etc/greetd/config.toml}}, if you use Cage, or in {{ic|/etc/greetd/sway-config}}, if you use Sway.<br />
<br />
==== wlgreet ====<br />
<br />
In order for greetd to start wlgreet, follow the steps required to set up gtkgreet with Sway as [[#gtkgreet|described above]] with the following {{ic|/etc/greetd/sway-config}} instead:<br />
exec "wlgreet --command sway; swaymsg exit"<br />
<br />
bindsym Mod4+shift+e exec swaynag \<br />
-t warning \<br />
-m 'What do you want to do?' \<br />
-b 'Poweroff' 'systemctl poweroff' \<br />
-b 'Reboot' 'systemctl reboot'<br />
<br />
include /etc/sway/config.d/*<br />
<br />
==== tuigreet ====<br />
<br />
tuigreet does not require any special setup, just refer to it in {{ic|/etc/greetd/config.toml}}:<br />
<br />
...<br />
[default_session]<br />
command = "tuigreet --cmd sway"<br />
...<br />
<br />
{{ic|tuigreet --help}} will display customization options.<br />
<br />
=== Autologin ===<br />
If you want a user to be logged in automatically, an {{ic|initial session}} must be defined in the configuration file:<br />
<br />
[default_session]<br />
command = "cage gtkgreet"<br />
<br />
[initial_session]<br />
command = "sway"<br />
user = "myuser"<br />
<br />
The ''command'' option may contain the name of any executable file.<br />
In the example above, Sway will be started by ''myuser'' at boot and gtkgreet will be launched after the user logs out.<br />
<br />
If you don't want to use greetd and always want autologin to be enabled, see [https://git.sr.ht/~kennylevinsen/autologin autologin].<br />
<br />
== Starting greetd at boot ==<br />
<br />
[[Enable]] {{ic|greetd.service}} for greetd to be started at boot.<br />
<br />
== See also ==<br />
<br />
* [https://sr.ht/~kennylevinsen/greetd/ greetd project page]<br />
* [https://git.sr.ht/~kennylevinsen/greetd/ greetd source code]<br />
* [https://man.sr.ht/%7Ekennylevinsen/greetd/ greetd wiki]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688624Git2021-07-20T02:29:35Z<p>Thiagowfx: /* Filtering confidential information */ expand link title</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Alternatively, edit {{ic|.git/config}} with the new location.<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches] and [https://git-send-email.io/ git-send-email.io]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''pacman-contrib@lists.archlinux.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
{{Note|Without {{ic|--tags}}, tags won't be fetched.}}<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653 Git filter and sed fight over `\$`].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688622Git2021-07-20T02:25:11Z<p>Thiagowfx: /* Partial fetch */ convert sentence into a note</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Alternatively, edit {{ic|.git/config}} with the new location.<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches] and [https://git-send-email.io/ git-send-email.io]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''pacman-contrib@lists.archlinux.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
{{Note|Without <code>--tags</code>, tags won't be fetched.}}<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688621Git2021-07-20T02:23:55Z<p>Thiagowfx: /* Directly sending patches to a mailing list */ use an arch-centric example: pacman-contrib</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Alternatively, edit {{ic|.git/config}} with the new location.<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches] and [https://git-send-email.io/ git-send-email.io]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''pacman-contrib@lists.archlinux.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
Without <code>--tags</code>, tags won't be fetched.<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688620Git2021-07-20T02:22:35Z<p>Thiagowfx: /* Directly sending patches to a mailing list */ add git-send-email.io</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Alternatively, edit {{ic|.git/config}} with the new location.<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches] and [https://git-send-email.io/ git-send-email.io]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''openembedded-core@lists.openembedded.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
Without <code>--tags</code>, tags won't be fetched.<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688619Git2021-07-20T02:18:44Z<p>Thiagowfx: /* Commit tips */ expand snippet about remote address changed</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Alternatively, edit {{ic|.git/config}} with the new location.<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''openembedded-core@lists.openembedded.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
Without <code>--tags</code>, tags won't be fetched.<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688618Git2021-07-20T02:15:29Z<p>Thiagowfx: /* Git prompt */ make it explicit the environment variable needs to be set</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt by setting the corresponding environment variable:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''openembedded-core@lists.openembedded.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
Without <code>--tags</code>, tags won't be fetched.<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Git&diff=688501Git2021-07-19T01:11:56Z<p>Thiagowfx: add VCS package guidelines to related section, and sort that list</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Commands]]<br />
[[de:Git]]<br />
[[es:Git]]<br />
[[ja:Git]]<br />
[[ko:Git]]<br />
[[zh-hans:Git]]<br />
{{Related articles start}}<br />
{{Related|Bisecting bugs with Git}}<br />
{{Related|Concurrent Versions System}}<br />
{{Related|Git server}}<br />
{{Related|Gitweb}}<br />
{{Related|HTTP tunneling#Tunneling Git}}<br />
{{Related|Subversion}}<br />
{{Related|VCS package guidelines}}<br />
{{Related articles end}}<br />
:"I've met people who thought git is a front-end to GitHub. They were wrong, git is a front-end to the AUR." — [https://public-inbox.org/git/#didyoureallythinklinuswouldsaythat Linus T.]<br />
<br />
[[wikipedia:Git (software)|Git]] is the version control system (VCS) designed and developed by Linus Torvalds, the creator of the Linux kernel. Git is now used to maintain [[AUR]] packages, as well as many other projects, including sources for the Linux kernel. <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|git}} package. For the development version, install the {{AUR|git-git}} package. Check the optional dependencies when using tools such as ''git svn'', ''git gui'' and ''gitk''.<br />
<br />
=== Graphical front-ends ===<br />
<br />
See also [https://git-scm.com/download/gui/linux git GUI Clients].<br />
<br />
* {{App|Giggle|GTK frontend for git.|https://wiki.gnome.org/Apps/giggle/|{{Pkg|giggle}}}}<br />
* {{App|GitAhead|Graphical git client including a built-in Merge Tool.|https://gitahead.github.io/gitahead.com/|{{AUR|gitahead}}}}<br />
* {{App|Git Cola|Sleek and powerful graphical user interface for Git written in Python.|https://git-cola.github.io/|{{AUR|git-cola}}}}<br />
* {{App|Git Extensions|Graphical user interface for Git that allows you to control Git without using the commandline.|https://gitextensions.github.io/|{{AUR|gitextensions}}}}<br />
* {{App|gitg|GNOME GUI client to view git repositories.|https://wiki.gnome.org/Apps/Gitg|{{Pkg|gitg}}}}<br />
* {{App|git-gui|Tcl/Tk based portable graphical interface to Git.|https://git-scm.com/docs/git-gui|{{Pkg|git}} + {{Pkg|tk}}}}<br />
:{{Note|To enable spell checking in ''git-gui'', {{Pkg|aspell}} is required, along with the dictionary corresponding to the {{ic|LC_MESSAGES}} [[environment variable]]. See {{Bug|28181}} and the [[aspell]] article.}}<br />
* {{App|GitHub Desktop|Electron-based graphical user interface built by the GitHub team.|https://github.com/desktop/desktop|{{AUR|github-desktop}} {{AUR|github-desktop-bin}}}}<br />
* {{App|gitk|Tcl/Tk based Git repository browser.|https://git-scm.com/docs/gitk|{{Pkg|git}} + {{Pkg|tk}}}}<br />
* {{App|Guitar|Git GUI Client.|https://github.com/soramimi/Guitar|{{AUR|guitar}}}}<br />
* {{App|QGit|Git GUI viewer to browse revisions history, view patch content and changed files, graphically following different development branches.|https://github.com/tibirna/qgit|{{Pkg|qgit}}}}<br />
* {{App|[[Wikipedia:RabbitVCS|RabbitVCS]]|Set of graphical tools written to provide simple and straightforward access to the version control systems you use.|http://rabbitvcs.org/|{{AUR|rabbitvcs}}}}<br />
* {{App|Sublime Merge|Git Client from the makers of Sublime Text. |https://www.sublimemerge.com/|{{AUR|sublime-merge}}}}<br />
* {{App|Tig|ncurses-based text-mode interface for git.|https://jonas.github.io/tig/|{{Pkg|tig}}}}<br />
* {{App|ungit|Brings user friendliness to git without sacrificing the versatility of git.|https://github.com/FredrikNoren/ungit|{{AUR|nodejs-ungit}}}}<br />
<br />
== Configuration ==<br />
<br />
In order to use Git you need to set at least a name and email:<br />
<br />
$ git config --global user.name "''John Doe''"<br />
$ git config --global user.email "''johndoe@example.com''"<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup].<br />
<br />
See [[#Tips and tricks]] for more settings.<br />
<br />
== Usage ==<br />
<br />
A Git repository is contained in a {{ic|.git}} directory, which holds the revision history and other metadata. The directory tracked by the repository, by default the parent directory, is called the working directory. Changes in the working tree need to be staged before they can be recorded (committed) to the repository. Git also lets you restore, previously committed, working tree files.<br />
<br />
See [https://git-scm.com/book/en/Getting-Started-Git-Basics Getting Started - Git Basics].<br />
<br />
=== Getting a Git repository ===<br />
<br />
* Initialize a repository<br />
:{{ic|git init}}, see {{man|1|git-init}}<br />
* Clone an existing repository<br />
:{{ic|git clone ''repository''}}, see {{man|1|git-clone}} (also explains the Git URLs)<br />
<br />
=== Recording changes ===<br />
<br />
Git projects have a staging area, which is an {{ic|index}} file in your Git directory, that stores the changes that will go into your next commit. To record a modified file you therefore firstly need to add it to the index (stage it). The {{ic|git commit}} command then stores the current index in a new commit.<br />
<br />
==== Staging changes ====<br />
<br />
* Add working tree changes to the index<br />
:{{ic|git add ''pathspec''}}, see {{man|1|git-add}}<br />
* Remove changes from the index<br />
:{{ic|git reset ''pathspec''}}, see {{man|1|git-reset}}<br />
* Show changes to be committed, unstaged changes and untracked files<br />
:{{ic|git status}}, see {{man|1|git-status}}<br />
<br />
You can tell Git to ignore certain untracked files using {{ic|.gitignore}} files, see {{man|5|gitignore}}.<br />
<br />
Git does not track file movement. Move detection during merges is based only on content similarity. The {{ic|git mv}} command is just there for convenience and is equivalent to:<br />
<br />
$ mv -i foo bar<br />
$ git reset -- foo<br />
$ git add bar<br />
<br />
==== Committing changes ====<br />
<br />
The {{ic|git commit}} command records the staged changes to the repository, see {{man|1|git-commit}}.<br />
<br />
* {{ic|-m}} – supply the commit message as an argument, instead of composing it in your default text editor<br />
* {{ic|-a}} – automatically stage files that have been modified or deleted (does not add untracked files)<br />
* {{ic|--amend}} – redo the last commit, amending the commit message or the committed files<br />
<br />
{{Tip|Always commit small changes frequently and with meaningful messages.}}<br />
<br />
==== Revision selection ====<br />
<br />
Git offers multiple ways to specify revisions, see {{man|7|gitrevisions}} and [https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection Revision Selection].<br />
<br />
Many Git commands take revisions as arguments. A commit can be identified by any of the following:<br />
<br />
* SHA-1 hash of the commit (the first 7 digits are usually sufficient to identify it uniquely)<br />
* Any commit label such as a branch or tag name<br />
* The label {{ic|HEAD}} always refers to the currently checked-out commit (usually the head of the branch, unless you used ''git checkout'' to jump back in history to an old commit)<br />
* Any of the above plus {{ic|~}} to refer to previous commits. For example, {{ic|HEAD~}} refers to one commit before {{ic|HEAD}} and {{ic|HEAD~5}} refers to five commits before {{ic|HEAD}}.<br />
<br />
==== Viewing changes ====<br />
<br />
Show differences between commits:<br />
<br />
$ git diff HEAD HEAD~3<br />
<br />
or between staging area and working tree:<br />
<br />
$ git diff<br />
<br />
View history of changes (where "''-N''" is the number of latest commits):<br />
<br />
$ git log -p ''(-N)''<br />
<br />
=== Undoing things ===<br />
<br />
* {{ic|git checkout}} - to restore working tree files, see {{man|1|git-checkout}}<br />
* {{ic|git reset}} - reset current HEAD to the specified state, see {{man|1|git-reset}}<br />
* {{ic|git revert}} - revert some existing commits, see {{man|1|git-revert}}<br />
<br />
These, along with few others, are further explained at [https://www.atlassian.com/git/tutorials/undoing-changes undoing-changes].<br />
<br />
For more complex modifications of history, such as {{ic|git commit --amend}} and {{ic|git rebase}} see, for example, [https://www.atlassian.com/git/tutorials/rewriting-history rewriting-history]. It is highly advised not to use such rewrites for commits that were collaborated with other users. Or, at the very least, highly coordinate it in advance.<br />
<br />
=== Branching ===<br />
<br />
{{Expansion|Add links for some common branching models.}}<br />
<br />
Fixes and new features are usually tested in branches. When changes are satisfactory they can merged back into the default (master) branch.<br />
<br />
Create a branch, whose name accurately reflects its purpose:<br />
<br />
$ git branch ''help-section-addition''<br />
<br />
List branches:<br />
<br />
$ git branch<br />
<br />
Switch branches:<br />
<br />
$ git checkout ''branch''<br />
<br />
Create and switch:<br />
<br />
$ git checkout -b ''branch''<br />
<br />
Merge a branch back to the master branch:<br />
<br />
$ git checkout master<br />
$ git merge ''branch''<br />
<br />
The changes will be merged if they do not conflict. Otherwise, Git will print an error message, and annotate files in the working tree to record the conflicts. The annotations can be displayed with {{ic|git diff}}. Conflicts are resolved by editing the files to remove the annotations, and committing the final version. See [[#Dealing with merges]] below.<br />
<br />
When done with a branch, delete it with:<br />
<br />
$ git branch -d ''branch''<br />
<br />
=== Collaboration ===<br />
<br />
A typical Git work-flow is:<br />
<br />
# Create a new repository or clone a remote one.<br />
# Create a branch to make changes; then commit those changes.<br />
# Consolidate commits for better organization/understanding.<br />
# Merge commits back into the main branch.<br />
# (Optional) Push changes to a remote server.<br />
<br />
==== Pull requests ====<br />
<br />
After making and committing some changes, the contributor can ask the original author to merge them. This is called a ''pull request''.<br />
<br />
To pull:<br />
<br />
$ git pull ''location'' master<br />
<br />
The ''pull'' command combines both ''fetching'' and ''merging''. If there are conflicts (e.g. the original author made changes in the same time span), then it will be necessary to manually fix them.<br />
<br />
Alternatively, the original author can pick the changes wanting to be incorporated. Using the ''fetch'' option (and ''log'' option with a special {{ic|FETCH_HEAD}} symbol), the contents of the pull request can be viewed before deciding what to do:<br />
<br />
$ git fetch ''location'' master<br />
$ git log -p HEAD..FETCH_HEAD<br />
$ git merge ''location'' master<br />
<br />
==== Using remotes ====<br />
<br />
Remotes are aliases for tracked remote repositories. A ''label'' is created defining a location. These labels are used to identify frequently accessed repositories.<br />
<br />
Create a remote:<br />
<br />
$ git remote add ''label'' ''location''<br />
<br />
Fetch a remote:<br />
<br />
$ git fetch ''label''<br />
<br />
Show differences between master and a remote master:<br />
<br />
$ git log -p master..''label''/master<br />
<br />
View remotes for the current repository:<br />
<br />
$ git remote -v<br />
<br />
When defining a remote that is a parent of the fork (the project lead), it is defined as ''upstream''.<br />
<br />
==== Push to a repository ====<br />
<br />
After being given rights from the original authors, push changes with:<br />
<br />
$ git push ''location'' ''branch''<br />
<br />
When ''git clone'' is performed, it records the original location and gives it a remote name of {{ic|origin}}.<br />
<br />
So what ''typically'' is done is this:<br />
<br />
$ git push origin master<br />
<br />
If the {{ic|-u}} ({{ic|--set-upstream}}) option is used, the location is recorded so the next time just a {{ic|git push}} is necessary.<br />
<br />
==== Dealing with merges ====<br />
<br />
See [https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts Basic Merge Conflicts] in the Git Book for a detailed explanation on how to resolve merge conflicts. Merges are generally reversible. If wanting to back out of a merge one can usually use the {{ic|--abort}} command (e.g. {{ic|git merge --abort}} or {{ic|git pull --abort}}).<br />
<br />
=== History and versioning ===<br />
<br />
==== Searching the history ====<br />
<br />
{{ic|git log}} will give the history with a commit checksum, author, date, and the short message. The ''checksum'' is the "object name" of a commit object, typically a 40-character SHA-1 hash.<br />
<br />
For history with a long message (where the "''checksum''" can be truncated, as long as it is unique):<br />
<br />
$ git show (''checksum'')<br />
<br />
Search for ''pattern'' in tracked files:<br />
<br />
$ git grep ''pattern''<br />
<br />
Search in {{ic|.c}} and {{ic|.h}} files:<br />
<br />
$ git grep ''pattern'' -- '*.[ch]'<br />
<br />
==== Tagging ====<br />
<br />
Tag commits for versioning:<br />
<br />
$ git tag 2.14 ''checksum''<br />
<br />
''Tagging'' is generally done for [https://www.drupal.org/node/1066342 releasing/versioning] but it can be any string. Generally annotated tags are used, because they get added to the Git database.<br />
<br />
Tag the current commit with:<br />
<br />
$ git tag -a 2.14 -m "Version 2.14"<br />
<br />
List tags:<br />
<br />
$ git tag -l<br />
<br />
Delete a tag:<br />
<br />
$ git tag -d 2.08<br />
<br />
Update remote tags:<br />
<br />
$ git push --tags<br />
<br />
==== Organizing commits ====<br />
<br />
Before submitting a pull request it may be desirable to consolidate/organize the commits. This is done with the ''git rebase'' {{ic|--interactive}} option:<br />
<br />
$ git rebase -i ''checksum''<br />
<br />
This will open the editor with a summary of all the commits in the range specified; in this case including the newest ({{ic|HEAD}}) back to, but excluding, commit {{ic|''checksum''}}. Or to use a number notation, use for example {{ic|HEAD~3}}, which will rebase the last three commits:<br />
<br />
pick d146cc7 Mountpoint test.<br />
pick 4f47712 Explain -o option in readme.<br />
pick 8a4d479 Rename documentation.<br />
<br />
Editing the action in the first column will dictate how the rebase will be done. The options are:<br />
<br />
* {{ic|pick}} — Apply this commit as is (the default).<br />
* {{ic|edit}} — Edit files and/or commit message.<br />
* {{ic|reword}} — Edit commit message.<br />
* {{ic|squash}} — Merge/fold into previous commit.<br />
* {{ic|fixup}} — Merge/fold into previous commit discarding its message.<br />
<br />
The commits can be re-ordered or erased from the history (but be very careful with these). After editing the file, Git will perform the specified actions; if prompted to resolve merge problems, fix them and continue with {{ic|git rebase --continue}} or back out with the {{ic|git rebase --abort}} command.<br />
<br />
{{Note|Squashing commits is only used for local commits, it will cause troubles on a repository that is shared by other people.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using git-config ===<br />
<br />
Git reads its configuration from four INI-type configuration files:<br />
<br />
* {{ic|/etc/gitconfig}} for system-wide defaults<br />
* {{ic|~/.gitconfig}} and {{ic|~/.config/git/config}} (since 1.7.12) for user-specific configuration<br />
* {{ic|.git/config}} for repository-specific configuration<br />
<br />
These files can be edited directly, but the usual method is to use ''git config'', as shown in the examples below.<br />
<br />
List the currently set variables:<br />
<br />
$ git config {--local,--global,--system} --list<br />
<br />
Set the default editor from [[vim]] to [[nano]]:<br />
<br />
$ git config --global core.editor "nano -w"<br />
<br />
Set the default push action:<br />
<br />
$ git config --global push.default simple<br />
<br />
Set a different tool for ''git difftool'' (''meld'' by default):<br />
<br />
$ git config --global diff.tool vimdiff<br />
<br />
See {{man|1|git-config}} and [https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration Git Configuration] for more information.<br />
<br />
=== Adopting a good etiquette ===<br />
<br />
* When considering contributing to an existing project, read and understand its license, as it may excessively limit your ability to change the code. Some licenses can generate disputes over the ownership of the code.<br />
* Think about the project's community and how well you can fit into it. To get a feeling of the direction of the project, read any documentation and even the [[#History and versioning|log]] of the repository.<br />
* When requesting to pull a commit, or submit a patch, keep it small and well documented; this will help the maintainers understand your changes and decide whether to merge them or ask you to make some amendments.<br />
* If a contribution is rejected, do not get discouraged, it is their project after all. If it is important, discuss the reasoning for the contribution as clearly and as patiently as possible: with such an approach a resolution may eventually be possible.<br />
<br />
=== Speeding up authentication ===<br />
<br />
You may wish to avoid the hassle of authenticating interactively at every push to the Git server.<br />
<br />
* If you are authenticating with SSH keys, use an [[SSH agent]]. See also [[OpenSSH#Speeding up SSH]] and [[OpenSSH#Keep alive]].<br />
* If you are authenticating with username and password, switch to [[SSH keys]] if the server supports SSH, otherwise use git-credential-libsecret credential helper, or try [https://git-scm.com/docs/git-credential-cache git-credential-cache] or [https://git-scm.com/docs/git-credential-store git-credential-store].<br />
<br />
=== Using git-credential-libsecret as credential-helper ===<br />
<br />
Git may fetch your credentials from a org.freedesktop.secrets compatible keyring like [[GNOME/Keyring]] or [[KeePassXC]]. Therefore set up one compatible keyring and check if a keyring is registered to dbus using:<br />
<br />
dbus-send --session --print-reply --dest=org.freedesktop.DBus / \<br />
org.freedesktop.DBus.GetConnectionUnixProcessID \<br />
string:org.freedesktop.secrets<br />
<br />
then run<br />
<br />
git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
to set up git.<br />
<br />
=== Protocol defaults ===<br />
<br />
If you are running a multiplexed SSH connection as shown above, Git over SSH might be faster than HTTPS. Also, some servers (like the AUR) only allow pushing via SSH. For example, the following config will set Git over SSH for any repository hosted on the AUR.<br />
<br />
{{hc|~/.gitconfig|<nowiki><br />
[url "ssh://aur@aur.archlinux.org/"]<br />
insteadOf &#61; https://aur.archlinux.org/<br />
insteadOf &#61; http://aur.archlinux.org/<br />
insteadOf &#61; git://aur.archlinux.org/<br />
</nowiki>}}<br />
<br />
=== Bash completion ===<br />
<br />
In order to enable Bash completion, source {{ic|/usr/share/git/completion/git-completion.bash}} in a [[Bash#Configuration_files|Bash startup file]]. Alternatively, install {{pkg|bash-completion}}.<br />
<br />
=== Git prompt ===<br />
<br />
The Git package comes with a prompt script. To enable it, source the {{ic|/usr/share/git/completion/git-prompt.sh}} and set a custom prompt with the {{ic|%s}} parameter:<br />
<br />
* For [[Bash]]: {{ic|1=PS1='[\u@\h \W$(__git_ps1 " (%s)")]\$ '}}<br />
* For [[zsh]]: {{ic|1=setopt PROMPT_SUBST ; PS1='[%n@%m %c$(__git_ps1 " (%s)")]\$ '}}<br />
<br />
Note that the command substitution must be escaped, see [[Bash/Prompt customization#Embedding commands]] for details. See [[Command-line shell#Configuration files]] for persistent configuration.<br />
<br />
When changing to a directory of a Git repository, the prompt will change to show the branch name. Extra details can be set to be shown by the prompt:<br />
<br />
{| class="wikitable"<br />
|+<br />
! Shell variable !! Information<br />
|-<br />
| GIT_PS1_SHOWDIRTYSTATE || '''+''' for staged, '''*''' if unstaged. <br />
|-<br />
| GIT_PS1_SHOWSTASHSTATE || '''$''' if something is stashed.<br />
|-<br />
| GIT_PS1_SHOWUNTRACKEDFILES || '''%''' if there are untracked files.<br />
|-<br />
| GIT_PS1_SHOWUPSTREAM || '''<,>,<>''' behind, ahead, or diverged from upstream.<br />
|}<br />
<br />
{{ic|GIT_PS1_SHOWUPSTREAM}} will need to be set to {{ic|auto}} for changes to take effect.<br />
<br />
{{Note|If you experience that {{ic|$(__git_ps1)}} returns {{ic|((unknown))}}, then there is a {{ic|.git}} folder in your current directory which does not contain any repository, and therefore Git does not recognize it. This can, for example, happen if you mistake Git's configuration file to be {{ic|~/.git/config}} instead of {{ic|~/.gitconfig}}.}}<br />
<br />
Alternatively, you can use one of git shell prompt customization packages from [[AUR]] such as {{AUR|bash-git-prompt}} or {{AUR|gittify}}.<br />
<br />
=== Visual representation ===<br />
<br />
To get an idea of the amount of work done:<br />
<br />
$ git diff --stat<br />
<br />
''git log'' with forking representation:<br />
<br />
$ git log --graph --oneline --decorate<br />
<br />
''git log'' graph alias (i.e. ''git graph'' will show a decorated version):<br />
<br />
$ git config --global alias.graph 'log --graph --oneline --decorate'<br />
<br />
=== Commit tips ===<br />
<br />
Reset to previous commit (very dangerous, erases everything to specified commit):<br />
<br />
$ git reset --hard HEAD^<br />
<br />
If a repository address gets changed, its remote location will need to be updated:<br />
<br />
$ git remote set-url origin git@''address'':''user''/''repo''.git<br />
<br />
Signed-off-by line append (a name-email signature is added to the commit which is required by some projects):<br />
<br />
$ git commit -s<br />
<br />
Signed-off-by automatically append to patches (when using {{ic|git format-patch ''commit''}}):<br />
<br />
$ git config --local format.signoff true<br />
<br />
Commit specific parts of files that have changed. This is useful if there are a large number of changes made that would be best split into several commits:<br />
<br />
$ git add -p<br />
<br />
=== Signing commits ===<br />
<br />
Git allows commits and tags to be signed using [[GnuPG]], see [https://git-scm.com/book/en/Git-Tools-Signing-Your-Work Signing Your Work].<br />
<br />
{{Note|To use [[pinentry]] curses for GPG signing make sure to {{ic|1=export GPG_TTY=$(tty)}} (alternatively use pinentry-tty) otherwise the signing step will fail if GPG is currently in a locked state (since it cannot prompt for pin).}}<br />
<br />
To configure Git to automatically sign commits:<br />
<br />
$ git config --global commit.gpgSign true<br />
<br />
=== Working with a non-master branch ===<br />
<br />
Occasionally a maintainer will ask that work be done on a branch. These branches are often called {{ic|devel}} or {{ic|testing}}. Begin by cloning the repository.<br />
<br />
To enter another branch beside master (''git clone'' only shows master branch but others still exist, {{ic|git branch -a}} to show):<br />
<br />
$ git checkout -b ''branch'' origin/''branch''<br />
<br />
Now edit normally; however to keep the repository tree in sync be sure to use both:<br />
<br />
$ git pull --all<br />
$ git push --all<br />
<br />
=== Directly sending patches to a mailing list ===<br />
<br />
If you want to send patches directly to a mailing list, you have to install the following packages: {{Pkg|perl-authen-sasl}} and {{Pkg|perl-io-socket-ssl}}.<br />
<br />
Make sure you have configured your username and e-mail address, see [[#Configuration]].<br />
<br />
Configure your e-mail settings:<br />
<br />
$ git config --global sendemail.smtpserver ''smtp.example.com''<br />
$ git config --global sendemail.smtpserverport ''587''<br />
$ git config --global sendemail.smtpencryption ''tls''<br />
$ git config --global sendemail.smtpuser ''foobar@example.com''<br />
<br />
Now you should be able to send the patch to the mailing list (see also [https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded#Sending_patches OpenEmbedded:How to submit a patch to OpenEmbedded#Sending patches]):<br />
<br />
$ git add ''filename''<br />
$ git commit -s<br />
$ git send-email --to=''openembedded-core@lists.openembedded.org'' --confirm=always -M -1<br />
<br />
=== When the remote repo is huge ===<br />
<br />
{{Style|Uses informal language, contractions, HTML tags instead of code templates and does not use interwiki links.}}<br />
<br />
When the remote repo is huge, the following solutions can be used. The examples are taken from the linux kernel.<br />
<br />
==== Simplest way: fetch the entire repo ====<br />
You can get the entire repository by<br />
<br />
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git<br />
<br />
{{Note|{{ic|git clone}} cannot be resumed if interrupted.}}<br />
<br />
You can update your repo by {{ic|git pull}}.<br />
<br />
==== Partial fetch ====<br />
Probably you want to limit your local repository smaller, say after v4.14 to bisect a bug. Then do:<br />
<br />
$ git clone --shallow-exclude v4.13 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git # You'll get v4.14 and later, but not v4.13 and older.<br />
<br />
Or maybe you only want the latest snapshot, ignoring all history. (If a tarball is available and it suffices, choose that. Getting a git repo costs more.) You can do it by:<br />
<br />
$ git clone --depth 1 git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git<br />
<br />
You can later obtain older commits, by e.g.<br />
<br />
$ git fetch --tags --shallow-exclude v4.1 # Get the commits after v4.1.<br />
$ git fetch --tags --shallow-since 2016-01-01<br />
<br />
Without <code>--tags</code>, tags won't be fetched.<br />
<br />
==== Get other branches ====<br />
Your local repo tracks, in the above example, only the mainline kernel, i.e. in which the ''latest development is done''. Suppose you want the latest ''LTS'', for example the up-to-date 4.14 branch. You can get it by:<br />
<br />
$ git remote set-branches --add origin linux-4.17.y<br />
$ git fetch<br />
$ git branch --track linux-4.17.y origin/linux-4.17.y<br />
<br />
The last line is not mandatory, but probably you want it.<br />
(To know the name of the branch you want, sorry, there's no general rule. You can guess one by seeing the "ref" link in the gitweb interface.) <br />
<br />
If you want the snapshot of linux-4.17.y, do<br />
<br />
$ git checkout -b linux-4.17.y<br />
<br />
Or to extract it in another directory,<br />
<br />
$ mkdir /foo/bar/src-4.17; cd /foo/bar/src-4.17<br />
$ git clone --no-local --depth 1 -b linux-4.17.y ../linux-stable<br />
<br />
As usual, do <code>git pull</code> to update your snapshot.<br />
<br />
==== Possible Future alternative ====<br />
Git Virtual Filesystem (GVFS), developed by Microsoft, allows you to access git repositories without a local one. (See [https://blogs.msdn.microsoft.com/bharry/2017/05/24/the-largest-git-repo-on-the-planet/ this Microsoft blog] or the [[wikipedia:Git_Virtual_File_System|Wikipedia article]].) It's not available in Linux yet.<br />
<br />
Anyway it is not for the above examples of the Linux kernel, though.<br />
<br />
=== Filtering confidential information ===<br />
<br />
Occasionally, software may keep plain-text passwords in configuration files, as opposed to hooking into a keyring. In these cases, git clean-filters may be handy to avoid accidentally commiting confidential information. E. g., the following file assigns a filter to the file “some-dotfile”:<br />
<br />
{{hc|.gitattributes|<nowiki><br />
some-dotfile filter=remove-pass<br />
</nowiki>}}<br />
<br />
Whenever the file “some-dotfile” is checked into git, git will invoke the filter “remove-pass” on the file before checking it in. The filter must be defined in the git-configuration file, e. g.:<br />
<br />
{{hc|.git/config|<nowiki><br />
[filter "remove-pass"]<br />
clean = "sed -e 's/^password=.*/#password=TODO/'"<br />
</nowiki>}}<br />
<br />
{{Note|Escaping special characters for sed expressions can be a [https://stackoverflow.com/questions/49652495/git-filter-and-sed-fight-over tricky task] in this context. Remember that git is turning two backslashes into one, while the shell that git invokes to run commands will again turn two backslashes into one. For more details, see [https://stackoverflow.com/a/49654653].}}<br />
<br />
=== HTML help files ===<br />
<br />
The {{ic|git help}} documentation is also available in HTML form by installing {{AUR|git-htmldocs}}. After installing, the HTML docs can be accessed by passing the {{ic|-w}} flag. For example:<br />
<br />
$ git help -w merge<br />
<br />
The HTML documentation can be loaded by default by setting a {{ic|git config}} option:<br />
<br />
$ git config --global help.format html<br />
<br />
== Extensions ==<br />
<br />
You can use [https://danielkummer.github.io/git-flow-cheatsheet/ gitflow] to easily manage a repository using [https://nvie.com/posts/a-successful-git-branching-model/ Vincent Driessen's branching model].<br />
<br />
* {{App|gitflow-avh|Extend git with Vincent Driessen's branching model. The AVH Edition adds more functionality.|https://github.com/petervanderdoes/gitflow/|{{AUR|gitflow-avh}}}}<br />
<br />
== See also ==<br />
<br />
* Git man pages, see {{man|1|git}}<br />
* [https://git-scm.com/book/en/ Pro Git book]<br />
* [https://git.github.io/git-reference/ Git Reference] by GitHub<br />
* [https://web.archive.org/web/20150316035247/https://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests Git workflow: Forks, remotes, and pull requests]<br />
* [https://wiki.videolan.org/Git VideoLAN wiki article]<br />
* [https://gist.github.com/grawity/4392747 A comparison of protocols GitHubGist]<br />
* [https://gun.io/blog/how-to-github-fork-branch-and-pull-request How to GitHub]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=GNOME/Keyring&diff=688494GNOME/Keyring2021-07-18T23:37:30Z<p>Thiagowfx: /* Git integration */ linkify libsecret package</p>
<hr />
<div>[[Category:GNOME]]<br />
[[es:GNOME (Español)/Keyring]]<br />
[[ja:GNOME Keyring]]<br />
[[zh-hans:GNOME (简体中文)/Keyring]]<br />
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."<br />
<br />
== Installation ==<br />
<br />
{{Pkg|gnome-keyring}} is a member of the {{Grp|gnome}} group is thus usually present on systems running GNOME. The package can otherwise be [[install]]ed on its own. {{Pkg|libsecret}} should also be installed to grant other applications access to your keyrings. Although {{Pkg|libgnome-keyring}} is deprecated (and superseded by ''libsecret''), it may still be required by certain applications.<br />
<br />
Extra utilities related to GNOME Keyring include:<br />
<br />
* {{App|secret-tool|Access the GNOME Keyring (and any other service implementing the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}<br />
* {{App|lssecret|List all secret items using ''libsecret'' (e.g. GNOME Keyring).|https://gitlab.com/GrantMoyer/lssecret|{{AUR|lssecret-git}}}}<br />
* {{App|gnome-keyring-query|Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.|[https://web.archive.org/web/20160326164641/https://gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases https://gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases] (archived)|{{AUR|gnome-keyring-query}}}}<br />
<br />
{{Note|''gnome-keyring-query'' only requires ''libgnome-keyring'' as a build dependency.}}<br />
<br />
== Manage using GUI ==<br />
<br />
You can manage the contents of GNOME Keyring using Seahorse; [[install]] the {{Pkg|seahorse}} package.<br />
<br />
Passwords for keyrings (e.g., the default keyring, "Login") can be changed and even removed. See [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-update-password.html Update the keyring password] in GNOME Help for more information.<br />
<br />
== Using the keyring ==<br />
<br />
The [[PAM]] module ''pam_gnome_keyring.so'' initialises GNOME Keyring partially, unlocking the default ''login'' keyring in the process. It should be followed by a call to ''gnome-keyring-daemon'' with the {{ic|--start}} option to complete initialisation and to set environment variables.<br />
<br />
=== PAM step ===<br />
<br />
{{Note|To use automatic unlocking '''without automatic login''', the password for the user account should be the same as the default keyring. See [[#Automatically change keyring password with user password]].}}<br />
{{Tip|<br />
* To use automatic unlocking with automatic login, you can set a blank password for the default keyring. Note that the contents of the keyring are stored unencrypted in this case.<br />
* Alternatively, if using GDM and LUKS, GDM can unlock your keyring if it matches your LUKS password. For this to work, you need to use the [[Mkinitcpio#Common hooks|systemd init in your mkinitcpio.conf]] as well as the [[Dm-crypt/System configuration#Using sd-encrypt hook|appropriate kernel parameters]]. See [https://reddit.com/r/Fedora/comments/jwnqq5/] for more details.<br />
* Skipping the PAM step works, because the [[#--start step|next step]] will initialise the daemon when one is not running already; however, the default keyring is not unlocked in this case. More details are available at [https://wiki.gnome.org/Projects/GnomeKeyring/RunningDaemon].<br />
}}<br />
<br />
When using a display manager, the keyring works out of the box for most cases. [[GDM]], [[LightDM]], [[LXDM]], and [[SDDM]] already have the necessary PAM configuration. For a display manager that does not automatically unlock the keyring edit the appropriate file instead of {{ic|/etc/pam.d/login}} as mentioned below.<br />
<br />
When using console-based login, edit {{ic|/etc/pam.d/login}}:<br />
<br />
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.<br />
<br />
{{hc|/etc/pam.d/login|<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_gnome_keyring.so'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_gnome_keyring.so auto_start'''<br />
}}<br />
<br />
If you are using GNOME, Unity, Cinnamon, or MATE, you are done. The initialisation is completed and environment variables are set automatically.<br />
<br />
=== --start step ===<br />
<br />
If you are '''not''' using GNOME, Unity, Mate, or Cinnamon as your desktop environment, initialisation will not complete automatically. You can fix this using various methods:<br />
<br />
==== Shell ====<br />
<br />
Add the following to your {{ic|~/.bash_profile}}, {{ic|~/.zshenv}}, or similar:<br />
<br />
{{hc|~/.bash_profile|2=<br />
if [ -n "$DESKTOP_SESSION" ];then<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
fi<br />
}}<br />
<br />
{{hc|~/.config/fish/config.fish|2=<br />
if test -n "$DESKTOP_SESSION"<br />
set -x (gnome-keyring-daemon --start {{!}} string split "=")<br />
end<br />
}}<br />
<br />
==== xinitrc ====<br />
<br />
Start the gnome-keyring-daemon from [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|2=<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
}}<br />
<br />
==== Xfce only ====<br />
<br />
See [[Xfce#SSH agents]] for use in Xfce.<br />
<br />
==== XDG autostart ====<br />
<br />
Copy {{ic|gnome-keyring-ssh.desktop}}, {{ic|gnome-keyring-pkcs11.desktop}}, and {{ic|gnome-keyring-secrets.desktop}} from {{ic|/etc/xdg/autostart/}} to {{ic|~/.config/autostart/}} and delete the {{ic|1=OnlyShowIn=GNOME;Unity;MATE;Cinnamon;}} lines from each file. Note however that this will '''not''' set {{ic|SSH_AUTH_SOCK}} (and the other variables if the PAM step was skipped) environment variable.<br />
<br />
== SSH keys ==<br />
<br />
'''gnome-keyring-daemon''' with the '''ssh''' component will start an SSH agent and automatically load all the keys in {{ic|~/.ssh/}} that have corresponding ''.pub'' files. There is no way to remove these keys from the agent.<br />
<br />
To list all loaded keys:<br />
<br />
$ ssh-add -L<br />
<br />
When you connect to a server that uses a loaded key with a password, a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!<br />
<br />
To permanently save the a passphrase in the keyring, use ssh-askpass from the {{pkg|seahorse}} package:<br />
<br />
$ /usr/lib/seahorse/ssh-askpass my_key<br />
<br />
To manually add an SSH key from another directory:<br />
<br />
$ ssh-add ~/.private/id_rsa<br />
Enter passphrase for ~/.private/id_rsa:<br />
<br />
{{Note|You have to have the corresponding ''.pub'' file in the same directory as the private key ({{ic|~/.ssh/id_rsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus ''.pub'' (for example, {{ic|my_key.pub}}).}}<br />
<br />
To disable all manually added keys:<br />
<br />
$ ssh-add -D<br />
<br />
=== Disable keyring daemon components ===<br />
<br />
If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]] or [[GnuPG#gpg-agent|gpg-agent]]), you need to disable the {{ic|ssh}} component of GNOME Keyring. To do so in an account-local way, copy {{ic|/etc/xdg/autostart/gnome-keyring-ssh.desktop}} to {{ic|~/.config/autostart/}} and then append the line {{ic|1=Hidden=true}} to the copied file. Then log out.<br />
<br />
{{Note|In case you use [[GNOME]] 3.24 or older on [[Wayland]], gnome-shell will overwrite {{ic|SSH_AUTH_SOCK}} to point to gnome-keyring regardless if it is running or not. To prevent this, you need to set the environment variable GSM_SKIP_SSH_AGENT_WORKAROUND before gnome-shell is started. One way to do this is to add the following line to {{ic|~/.pam_environment}}:<br />
<br />
{{bc|1=GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT=1}}<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Integration with applications ===<br />
<br />
* [[Chromium#Force a password store|Chromium]]<br />
<br />
=== Flushing passphrases ===<br />
<br />
$ gnome-keyring-daemon -r -d<br />
<br />
This command starts gnome-keyring-daemon, shutting down previously running instances.<br />
<br />
=== Git integration ===<br />
<br />
The GNOME keyring is useful in conjunction with [[Git]] when you are pushing over HTTPS. {{Pkg|libsecret}} [[#Installation|needs to be installed for this functionality to be available]].<br />
<br />
Configure Git to use the ''libsecret'' helper:<br />
<br />
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
The next time you run {{ic|git push}}, you will be asked to unlock your keyring if it is not already unlocked.<br />
<br />
=== GnuPG integration ===<br />
<br />
Several applications which use GnuPG require a {{ic|pinentry-program}} to be set. Set the following to use GNOME 3 pinentry for GNOME Keyring to manage passphrase prompts.<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
}}<br />
<br />
Another option is to [[GnuPG#Unattended_passphrase|force loopback for GPG]] which should allow the passphrase to be entered in the application.<br />
<br />
=== Renaming a keyring ===<br />
<br />
The display name for a keyring (i.e., the name that appears in Seahorse and from {{ic|file}}) can be changed by [https://ttboj.wordpress.com/2013/01/27/renaming-a-gnome-keyring-for-seahorse-the-passwords-and-keyrings-application/ changing the value of display-name in the unencrypted keyring file]. Keyrings will usually be stored in {{ic|~/.local/share/keyrings/}} with the ''.keyring'' file extension.<br />
<br />
=== Automatically change keyring password with user password ===<br />
<br />
{{Note|This only affects the default keyring.}}<br />
<br />
Add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
'''password optional pam_gnome_keyring.so'''<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you are prompted for a password after logging in and you find that your passwords are not saved, then you may need to create/set a default keyring. To do this using Seahorse (a.k.a. Passwords and Keys), see [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-change-default.html Change the default keyring] in GNOME Help.<br />
<br />
=== Resetting the keyring ===<br />
<br />
You will need to [[#Manage using GUI|change your login keyring password]] if you receive the following error message: "The password you use to login to your computer no longer matches that of your login keyring".<br />
<br />
Alternatively, you can remove the {{ic|login.keyring}} and {{ic|user.keystore}} files from {{ic|~/.local/share/keyrings/}}. Be warned that this will permanently delete all saved keys. After removing the files, simply log out and log in again.<br />
<br />
== See also ==<br />
<br />
* [https://help.gnome.org/users/seahorse/stable/ GNOME Help page]<br />
* [https://wiki.gnome.org/action/show/Projects/GnomeKeyring GNOME Wiki page]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=GNOME/Keyring&diff=688493GNOME/Keyring2021-07-18T23:33:13Z<p>Thiagowfx: /* xinitrc */ make gnome-keyring-daemon example consistent with the shell example</p>
<hr />
<div>[[Category:GNOME]]<br />
[[es:GNOME (Español)/Keyring]]<br />
[[ja:GNOME Keyring]]<br />
[[zh-hans:GNOME (简体中文)/Keyring]]<br />
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."<br />
<br />
== Installation ==<br />
<br />
{{Pkg|gnome-keyring}} is a member of the {{Grp|gnome}} group is thus usually present on systems running GNOME. The package can otherwise be [[install]]ed on its own. {{Pkg|libsecret}} should also be installed to grant other applications access to your keyrings. Although {{Pkg|libgnome-keyring}} is deprecated (and superseded by ''libsecret''), it may still be required by certain applications.<br />
<br />
Extra utilities related to GNOME Keyring include:<br />
<br />
* {{App|secret-tool|Access the GNOME Keyring (and any other service implementing the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}<br />
* {{App|lssecret|List all secret items using ''libsecret'' (e.g. GNOME Keyring).|https://gitlab.com/GrantMoyer/lssecret|{{AUR|lssecret-git}}}}<br />
* {{App|gnome-keyring-query|Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.|[https://web.archive.org/web/20160326164641/https://gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases https://gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases] (archived)|{{AUR|gnome-keyring-query}}}}<br />
<br />
{{Note|''gnome-keyring-query'' only requires ''libgnome-keyring'' as a build dependency.}}<br />
<br />
== Manage using GUI ==<br />
<br />
You can manage the contents of GNOME Keyring using Seahorse; [[install]] the {{Pkg|seahorse}} package.<br />
<br />
Passwords for keyrings (e.g., the default keyring, "Login") can be changed and even removed. See [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-update-password.html Update the keyring password] in GNOME Help for more information.<br />
<br />
== Using the keyring ==<br />
<br />
The [[PAM]] module ''pam_gnome_keyring.so'' initialises GNOME Keyring partially, unlocking the default ''login'' keyring in the process. It should be followed by a call to ''gnome-keyring-daemon'' with the {{ic|--start}} option to complete initialisation and to set environment variables.<br />
<br />
=== PAM step ===<br />
<br />
{{Note|To use automatic unlocking '''without automatic login''', the password for the user account should be the same as the default keyring. See [[#Automatically change keyring password with user password]].}}<br />
{{Tip|<br />
* To use automatic unlocking with automatic login, you can set a blank password for the default keyring. Note that the contents of the keyring are stored unencrypted in this case.<br />
* Alternatively, if using GDM and LUKS, GDM can unlock your keyring if it matches your LUKS password. For this to work, you need to use the [[Mkinitcpio#Common hooks|systemd init in your mkinitcpio.conf]] as well as the [[Dm-crypt/System configuration#Using sd-encrypt hook|appropriate kernel parameters]]. See [https://reddit.com/r/Fedora/comments/jwnqq5/] for more details.<br />
* Skipping the PAM step works, because the [[#--start step|next step]] will initialise the daemon when one is not running already; however, the default keyring is not unlocked in this case. More details are available at [https://wiki.gnome.org/Projects/GnomeKeyring/RunningDaemon].<br />
}}<br />
<br />
When using a display manager, the keyring works out of the box for most cases. [[GDM]], [[LightDM]], [[LXDM]], and [[SDDM]] already have the necessary PAM configuration. For a display manager that does not automatically unlock the keyring edit the appropriate file instead of {{ic|/etc/pam.d/login}} as mentioned below.<br />
<br />
When using console-based login, edit {{ic|/etc/pam.d/login}}:<br />
<br />
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.<br />
<br />
{{hc|/etc/pam.d/login|<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_gnome_keyring.so'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_gnome_keyring.so auto_start'''<br />
}}<br />
<br />
If you are using GNOME, Unity, Cinnamon, or MATE, you are done. The initialisation is completed and environment variables are set automatically.<br />
<br />
=== --start step ===<br />
<br />
If you are '''not''' using GNOME, Unity, Mate, or Cinnamon as your desktop environment, initialisation will not complete automatically. You can fix this using various methods:<br />
<br />
==== Shell ====<br />
<br />
Add the following to your {{ic|~/.bash_profile}}, {{ic|~/.zshenv}}, or similar:<br />
<br />
{{hc|~/.bash_profile|2=<br />
if [ -n "$DESKTOP_SESSION" ];then<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
fi<br />
}}<br />
<br />
{{hc|~/.config/fish/config.fish|2=<br />
if test -n "$DESKTOP_SESSION"<br />
set -x (gnome-keyring-daemon --start {{!}} string split "=")<br />
end<br />
}}<br />
<br />
==== xinitrc ====<br />
<br />
Start the gnome-keyring-daemon from [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|2=<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
}}<br />
<br />
==== Xfce only ====<br />
<br />
See [[Xfce#SSH agents]] for use in Xfce.<br />
<br />
==== XDG autostart ====<br />
<br />
Copy {{ic|gnome-keyring-ssh.desktop}}, {{ic|gnome-keyring-pkcs11.desktop}}, and {{ic|gnome-keyring-secrets.desktop}} from {{ic|/etc/xdg/autostart/}} to {{ic|~/.config/autostart/}} and delete the {{ic|1=OnlyShowIn=GNOME;Unity;MATE;Cinnamon;}} lines from each file. Note however that this will '''not''' set {{ic|SSH_AUTH_SOCK}} (and the other variables if the PAM step was skipped) environment variable.<br />
<br />
== SSH keys ==<br />
<br />
'''gnome-keyring-daemon''' with the '''ssh''' component will start an SSH agent and automatically load all the keys in {{ic|~/.ssh/}} that have corresponding ''.pub'' files. There is no way to remove these keys from the agent.<br />
<br />
To list all loaded keys:<br />
<br />
$ ssh-add -L<br />
<br />
When you connect to a server that uses a loaded key with a password, a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!<br />
<br />
To permanently save the a passphrase in the keyring, use ssh-askpass from the {{pkg|seahorse}} package:<br />
<br />
$ /usr/lib/seahorse/ssh-askpass my_key<br />
<br />
To manually add an SSH key from another directory:<br />
<br />
$ ssh-add ~/.private/id_rsa<br />
Enter passphrase for ~/.private/id_rsa:<br />
<br />
{{Note|You have to have the corresponding ''.pub'' file in the same directory as the private key ({{ic|~/.ssh/id_rsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus ''.pub'' (for example, {{ic|my_key.pub}}).}}<br />
<br />
To disable all manually added keys:<br />
<br />
$ ssh-add -D<br />
<br />
=== Disable keyring daemon components ===<br />
<br />
If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]] or [[GnuPG#gpg-agent|gpg-agent]]), you need to disable the {{ic|ssh}} component of GNOME Keyring. To do so in an account-local way, copy {{ic|/etc/xdg/autostart/gnome-keyring-ssh.desktop}} to {{ic|~/.config/autostart/}} and then append the line {{ic|1=Hidden=true}} to the copied file. Then log out.<br />
<br />
{{Note|In case you use [[GNOME]] 3.24 or older on [[Wayland]], gnome-shell will overwrite {{ic|SSH_AUTH_SOCK}} to point to gnome-keyring regardless if it is running or not. To prevent this, you need to set the environment variable GSM_SKIP_SSH_AGENT_WORKAROUND before gnome-shell is started. One way to do this is to add the following line to {{ic|~/.pam_environment}}:<br />
<br />
{{bc|1=GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT=1}}<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Integration with applications ===<br />
<br />
* [[Chromium#Force a password store|Chromium]]<br />
<br />
=== Flushing passphrases ===<br />
<br />
$ gnome-keyring-daemon -r -d<br />
<br />
This command starts gnome-keyring-daemon, shutting down previously running instances.<br />
<br />
=== Git integration ===<br />
<br />
The GNOME keyring is useful in conjunction with [[Git]] when you are pushing over HTTPS. [[#Installation|libsecret needs to be installed for this functionality to be available]].<br />
<br />
Configure Git to use the ''libsecret'' helper:<br />
<br />
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret<br />
<br />
The next time you run {{ic|git push}}, you will be asked to unlock your keyring if it is not already unlocked.<br />
<br />
=== GnuPG integration ===<br />
<br />
Several applications which use GnuPG require a {{ic|pinentry-program}} to be set. Set the following to use GNOME 3 pinentry for GNOME Keyring to manage passphrase prompts.<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
}}<br />
<br />
Another option is to [[GnuPG#Unattended_passphrase|force loopback for GPG]] which should allow the passphrase to be entered in the application.<br />
<br />
=== Renaming a keyring ===<br />
<br />
The display name for a keyring (i.e., the name that appears in Seahorse and from {{ic|file}}) can be changed by [https://ttboj.wordpress.com/2013/01/27/renaming-a-gnome-keyring-for-seahorse-the-passwords-and-keyrings-application/ changing the value of display-name in the unencrypted keyring file]. Keyrings will usually be stored in {{ic|~/.local/share/keyrings/}} with the ''.keyring'' file extension.<br />
<br />
=== Automatically change keyring password with user password ===<br />
<br />
{{Note|This only affects the default keyring.}}<br />
<br />
Add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
'''password optional pam_gnome_keyring.so'''<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you are prompted for a password after logging in and you find that your passwords are not saved, then you may need to create/set a default keyring. To do this using Seahorse (a.k.a. Passwords and Keys), see [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-change-default.html Change the default keyring] in GNOME Help.<br />
<br />
=== Resetting the keyring ===<br />
<br />
You will need to [[#Manage using GUI|change your login keyring password]] if you receive the following error message: "The password you use to login to your computer no longer matches that of your login keyring".<br />
<br />
Alternatively, you can remove the {{ic|login.keyring}} and {{ic|user.keystore}} files from {{ic|~/.local/share/keyrings/}}. Be warned that this will permanently delete all saved keys. After removing the files, simply log out and log in again.<br />
<br />
== See also ==<br />
<br />
* [https://help.gnome.org/users/seahorse/stable/ GNOME Help page]<br />
* [https://wiki.gnome.org/action/show/Projects/GnomeKeyring GNOME Wiki page]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=General_troubleshooting&diff=685428General troubleshooting2021-07-05T03:17:16Z<p>Thiagowfx: /* Debugging freezes */ style</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:System recovery]]<br />
[[Category:Installation process]]<br />
[[es:General troubleshooting]]<br />
[[fr:General troubleshooting]]<br />
[[ja:一般的なトラブルシューティング]]<br />
[[ru:General troubleshooting]]<br />
[[zh-hans:General troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debugging/Getting traces}}<br />
{{Related articles end}}<br />
<br />
This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.<br />
<br />
== General procedures ==<br />
<br />
It is crucial to ''always'' read any error messages that appear. Sometimes it may be hard, e.g with graphical applications, to get a proper error message.<br />
<br />
# Run the application in a terminal so it is possible to inspect the output.<br />
## Increase the verbosity (usually {{ic|--verbose}}/{{ic|-v}}/{{ic|-V}} or {{ic|--debug}}/{{ic|-d}}) if there is still not enough information to debug.<br />
## Sometimes there is no such parameter and it needs to be specified as a directive in the applications' configuration file.<br />
## An application may also use log files, which are usually located in {{ic|/var/log}}, {{ic|$HOME/.cache}} or {{ic|$HOME/.local}}<br />
## If there is no way to increase the verbosity, it is always possible to run [[strace]] and similar.<br />
# Check the [[journal]]. It is possible that an error may also leave traces in the journal, especially if it depends on other applications.<br />
## {{ic|dmesg}} reads from the kernel ring buffer. This is useful if the disk is for some reason inaccessible but this may also result in incomplete logs because the kernel ring buffer is not infinite in size. Use {{ic|journalctl}} if possible.<br />
## {{ic|journalctl}} has more filtering options than {{ic|dmesg}} and uses human-readable timestamps by default.<br />
# It is always recommended to check the relevant issue trackers to see if there are known issues with already existing solutions.<br />
## Depending on upstreams' choices, there is usually an issue tracker and sometimes also a forum or even e.g an IRC channel.<br />
## There is the [https://bugs.archlinux.org Arch Linux bugtracker], which should be primarily used for packaging bugs.<br />
<br />
=== Additional support ===<br />
<br />
If you require any additional support, you may ask on [https://bbs.archlinux.org the forums] or on [[IRC]].<br />
<br />
{{Note|[[Code of conduct#arch-linux-distribution-support-only|Support is provided for Arch Linux ONLY]] and not [[Arch-based distributions]].}}<br />
<br />
When asking for support post the '''complete''' output/logs, not just what you think are the significant sections. Sources of information include:<br />
<br />
* Full output of any command involved - do not just select what you think is relevant.<br />
* systemd's [[journal]].<br />
** For more extensive output, use the {{ic|1=systemd.log_level=debug}} boot parameter. This will produce a tremendous amount of output, so only enable it if it really needed.<br />
** Do not use the {{ic|-x}} parameter because this needlessly clutters the output and makes it harder to read.<br />
** Use {{ic|-b}} unless you need logs from a previous boot. Not specifying this may lead to extremely large pastes and may even be to big for any pastebins.<br />
* Relevant configuration files<br />
* Drivers involved<br />
* Versions of packages involved<br />
* Kernel: {{ic|journalctl -k}} or {{ic|dmesg}} (both with root privileges).<br />
* [[Xorg]]: depending on the setup the [[display manager]] in use is relevant here, too.<br />
** {{ic|Xorg.log}} may be located in one of several places: the system journal, {{ic|/var/log/}} or {{ic|$HOME/.local/share/xorg/}}.<br />
** Some display managers like [[LightDM]] may also place the {{ic|Xorg.log}} in its own log directory.<br />
* [[Pacman]]: If a recent upgrade broke something, look in {{ic|/var/log/pacman.log}}.<br />
** It may be useful to use pacman's {{ic|--debug}} parameter.<br />
<br />
One of the better ways to post this information is to use a [[#IRC collaborative debugging|pastebin]].<br />
<br />
A link will then be output that you can paste to the forum or IRC.<br />
<br />
Additionally, you may wish to review [https://www.co.kerr.tx.us/it/howtoreport.html how to properly report issues] before asking.<br />
<br />
== Boot problems ==<br />
<br />
When diagnosing boot problems, it is very important to know in which stage the boot fails.<br />
<br />
# BIOS/Firmware<br />
## Usually only has very basic tools for debugging.<br />
## Make sure [[Secure Boot]] is disabled.<br />
# [[Bootloader]]<br />
## One of the most common things done here is the changing of kernel parameters.<br />
# [[Initramfs]]<br />
## Usually provides an emergency shell.<br />
## Depending on the hooks chosen, either the dmesg or the journal is available within it.<br />
# The actual system<br />
## Depending on how badly it is broken, a simple invocation of the [[#Recovery shells|debug shell]] may suffice here.<br />
<br />
Unfortunately, the debugging tools provided by any stage may not be enough to fix the broken component. The [[archiso]] may be used to recover in this case.<br />
<br />
=== Console messages ===<br />
<br />
After the boot process, the screen is cleared and the login prompt appears, leaving users unable to read init output and error messages. This default behavior may be modified using methods outlined in the sections below.<br />
<br />
Note that regardless of the chosen option, kernel messages can be displayed for inspection after booting by using {{ic|journalctl -k}} or {{ic|dmesg}}. To display all logs from the current boot use {{ic|journalctl -b}}.<br />
<br />
==== Flow control ====<br />
<br />
This is basic management that applies to most terminal emulators, including virtual consoles (vc):<br />
<br />
* Press {{ic|Ctrl+s}} to pause the output<br />
* And {{ic|Ctrl+q}} to resume it<br />
<br />
This pauses not only the output, but also programs which try to print to the terminal, as they will block on the {{ic|write()}} calls for as long as the output is paused. If your ''init'' appears frozen, make sure the system console is not paused.<br />
<br />
To see error messages which are already displayed, see [[Getty#Have boot messages stay on tty1]].<br />
<br />
==== Debug output ====<br />
<br />
Most kernel messages are hidden during boot. You can see more of these messages by adding different kernel parameters. The simplest ones are:<br />
<br />
* {{ic|debug}} enables debug messages for both the kernel and [[systemd]]<br />
* {{ic|ignore_loglevel}} forces ''all'' kernel messages to be printed<br />
<br />
Other parameters you can add that might be useful in certain situations are:<br />
* {{ic|1=earlyprintk=vga,keep}} prints kernel messages very early in the boot process, in case the kernel would crash before output is shown. You must change {{ic|vga}} to {{ic|efi}} for [[EFI]] systems<br />
* {{ic|1=log_buf_len=16M}} allocates a larger (16 MiB) kernel message buffer, to ensure that debug output is not overwritten<br />
<br />
There are also a number of separate debug parameters for enabling debugging in specific subsystems e.g. {{ic|bootmem_debug}}, {{ic|sched_debug}}. Also, {{ic|initcall_debug}} can be useful to investigate boot freezes. (Look for calls that did not return.) Check the [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel parameter documentation] for specific information.<br />
<br />
==== netconsole ====<br />
<br />
[https://www.kernel.org/doc/html/latest/networking/netconsole.html netconsole] is a kernel module that sends all kernel log messages (i.e. dmesg) over the network to another computer, without involving user space (e.g. syslogd). Name "netconsole" is a misnomer because it is not really a "console", more like a remote logging service.<br />
<br />
It can be used either built-in or as a module. Built-in ''netconsole'' initializes immediately after NIC cards and will bring up the specified interface as soon as possible. The module is mainly used for capturing kernel panic output from a headless machine, or in other situations where the user space is no more functional.<br />
<br />
=== Recovery shells ===<br />
<br />
Getting an interactive shell at some stage in the boot process can help you pinpoint exactly where and why something is failing. There are several kernel parameters for doing so, but they all launch a normal shell which you can {{ic|exit}} to let the kernel resume what it was doing:<br />
* {{ic|rescue}} launches a shell shortly after the root filesystem is remounted read/write<br />
* {{ic|emergency}} launches a shell even earlier, before most filesystems are mounted<br />
* {{ic|1=init=/bin/sh}} (as a last resort) changes the init program to a root shell. {{ic|rescue}} and {{ic|emergency}} both rely on [[systemd]], but this should work even if ''systemd'' is broken<br />
<br />
Another option is systemd's debug-shell which adds a root shell on {{ic|tty9}} (accessible with {{ic|Ctrl+Alt+F9}}). It can be enabled by either adding {{ic|systemd.debug_shell}} to the [[kernel parameters]], or by [[enabling]] {{ic|debug-shell.service}}.<br />
<br />
{{Warning|Remember to disable the service when done to avoid the security risk of leaving a root shell open on every boot.}}<br />
<br />
=== Debugging kernel modules ===<br />
<br />
See [[Kernel modules#Obtaining information]].<br />
<br />
=== Debugging hardware ===<br />
<br />
* You can display extra debugging information about your hardware by following [[udev#Debug output]].<br />
* Ensure that [[Microcode]] updates are applied on your system.<br />
* To test the RAM, see [[Stress testing#Stressing memory]].<br />
<br />
== Debugging freezes ==<br />
<br />
Unfortunately, freezes are usually hard to debug and some of them take a lot of time to reproduce. There are some types of freezes which are easier to debug than others:<br />
<br />
* Is sound still playing? If so, just the display may be frozen. This may be a problem with the video driver.<br />
* Is the machine still responding? Try [[SSH]] if switching to another [[Tty|TTY]] does not work.<br />
* Is the disk activity LED (if present) indicating that a lot is being written to disk? Heavy swapping may temporarily freeze the system. See [https://unix.stackexchange.com/a/340567 this StackExchange answer] for information about freezes on large writes.<br />
<br />
If nothing else helps, try a '''clean''' shutdown. Pressing the power button ''once'' may unfreeze the system and show the classic "shutdown screen" which displays all the units that are getting stopped. Alternatively, using the magic [[SysRq]] keys may also help to achieve a clean shutdown. This is very important because the [[journal]] may contain hints why the machine froze. The journal may not be written to disk on an unclean shutdown. Hard freezes in which the whole machine is unresponsible are harder to debug since logs can not be written to disk in time.<br />
<br />
Remote logging may help if the freeze does not permit writing anything to disk. A crude remote logging solution, which needs to be invoked from another device, can be used for basic debugging:<br />
<br />
$ ssh ''<freezing host>'' journalctl -f<br />
<br />
Many fatal freezes in which the whole system does not respond anymore and require a forced shutdown may be related to buggy firmware, drivers or hardware. Trying a different kernel (see [[Kernel#Debugging regressions]]) or even a different Linux distribution or operating system, updating the firmware and running hardware diagnostics may help finding the problem.<br />
<br />
{{Tip|It is recommended to try to update the firmware of the device, since these updates may fix strange issues.}}<br />
<br />
If a freeze does not permit gathering any kind of logs or other information required for debugging, try reproducing the freeze in a live environment. If a graphical environment is required to reproduce the freeze or if the freeze can be reproduced on the archiso, use the live environment of a different distribution, which is preferably not based on Arch Linux to eliminate the possibility that the freeze is related to the version or patches of the kernel.<br />
Should the freeze still happen in a live environment, chances are that it ''may'' be hardware-related. If it does not happen anymore, it is necessary to be aware of the differences of both systems. Different configurations, differences in versions and kernel parameters and other, similar changes may have fixed the freeze.<br />
<br />
However, a blinking caps lock LED may indicate a [[kernel panic]]. Some setups may not show the TTY when a kernel panic occurred, which may be confusing and can be interpreted as another kind of freeze.<br />
<br />
== Debugging regressions ==<br />
<br />
If an update causes an issue but [[downgrading]] the specific package fixes it, it is likely a [[wikipedia:Software regression|regression]]. The most important part of debugging regressions is checking if the issue was already fixed, as this can save much time. To do so, first ensure the application is fully updated (e.g ensure the application is the same version as in the [[official repositories]]). If it already is or if updating it does not fix the issue, try using the the actual latest version, usually a [[Arch User Repository#What is the difference between foo and foo-git packages?|-git]] version, which are may be already packaged in the [[AUR]]. If this fixes the issue and the version with the fixes is not yet in the official repositories, wait until the new version arrives in them and then switch back to it.<br />
<br />
If the issue still persists, debug the issue and/or [[bisect]] the application and report the bug on the upstream bugtracker so it can be fixed.<br />
<br />
{{Note|The kernel needs a [[Kernel#Debugging regressions|slightly different approach]] when debugging regressions.}}<br />
<br />
== Kernel panics ==<br />
<br />
A ''kernel panic'' occurs when the Linux kernel enters an unrecoverable failure state. The state typically originates from buggy hardware drivers resulting in the machine being deadlocked, non-responsive, and requiring a reboot. Just prior to deadlock, a diagnostic message is generated, consisting of: the ''machine state'' when the failure occurred, a ''call trace'' leading to the kernel function that recognized the failure, and a listing of currently loaded modules. Thankfully, kernel panics do not happen very often using ''mainline'' versions of the kernel--such as those supplied by the official repositories--but when they do happen, you need to know how to deal with them.<br />
<br />
{{Note|Kernel panics are sometimes referred to as ''oops'' or ''kernel oops''. While both panics and oops occur as the result of a failure state, an ''oops'' is more general in that it does not ''necessarily'' result in a deadlocked machine--sometimes the kernel can recover from an oops by killing the offending task and carrying on.}}<br />
<br />
{{Tip|Pass the kernel parameter {{ic|1=oops=panic}} at boot or write {{ic|1}} to {{ic|/proc/sys/kernel/panic_on_oops}} to force a recoverable oops to issue a panic instead. This is advisable if you are concerned about the small chance of system instability resulting from an oops recovery which may make future errors difficult to diagnose.}}<br />
<br />
=== Examine panic message ===<br />
<br />
If a kernel panic occurs very early in the boot process, you may see a message on the console containing "Kernel panic - not syncing:", but once [[Systemd]] is running, kernel messages will typically be captured and written to the system log. However, when a panic occurs, the diagnostic message output by the kernel is ''almost never'' written to the log file on disk because the machine deadlocks before {{ic|system-journald}} gets the chance. Therefore, the only way to examine the panic message is to view it on the console as it happens (without resorting to setting up a ''kdump crashkernel''). You can do this by booting with the following kernel parameters and attempting to reproduce the panic on tty1:<br />
<br />
{{bc|1=systemd.journald.forward_to_console=1 console=tty1}}<br />
<br />
{{Tip|In the event that the panic message scrolls away too quickly to examine, try passing the kernel parameter {{ic|1=pause_on_oops=''seconds''}} at boot.}}<br />
<br />
==== Example scenario: bad module ====<br />
<br />
It is possible to make a best guess as to what subsystem or module is causing the panic using the information in the diagnostic message. In this scenario, we have a panic on some imaginary machine during boot. Pay attention to the lines highlighted in '''bold''':<br />
<br />
{{bc|'''kernel: BUG: unable to handle kernel NULL pointer dereference at (null)''' [1]<br />
'''kernel: IP: fw_core_init+0x18/0x1000 [firewire_core]''' [2]<br />
kernel: PGD 718d00067<br />
kernel: P4D 718d00067<br />
kernel: PUD 7b3611067<br />
kernel: PMD 0<br />
kernel:<br />
kernel: Oops: 0002 [#1] PREEMPT SMP<br />
'''kernel: Modules linked in: firewire_core(+) crc_itu_t cfg80211 rfkill ipt_REJECT nf_reject_ipv4 nf_log_ipv4 nf_log_common xt_LOG nf_conntrack_ipv4 ...''' [3]<br />
kernel: CPU: 6 PID: 1438 Comm: modprobe Tainted: P O 4.13.3-1-ARCH #1<br />
kernel: Hardware name: Gigabyte Technology Co., Ltd. H97-D3H/H97-D3H-CF, BIOS F5 06/26/2014<br />
kernel: task: ffff9c667abd9e00 task.stack: ffffb53b8db34000<br />
kernel: RIP: 0010:fw_core_init+0x18/0x1000 [firewire_core]<br />
kernel: RSP: 0018:ffffb53b8db37c68 EFLAGS: 00010246<br />
kernel: RAX: 0000000000000000 RBX: 0000000000000000 RCX: 0000000000000000<br />
kernel: RDX: 0000000000000000 RSI: 0000000000000008 RDI: ffffffffc16d3af4<br />
kernel: RBP: ffffb53b8db37c70 R08: 0000000000000000 R09: ffffffffae113e95<br />
kernel: R10: ffffe93edfdb9680 R11: 0000000000000000 R12: ffffffffc16d9000<br />
kernel: R13: ffff9c6729bf8f60 R14: ffffffffc16d5710 R15: ffff9c6736e55840<br />
kernel: FS: 00007f301fc80b80(0000) GS:ffff9c675dd80000(0000) knlGS:0000000000000000<br />
kernel: CS: 0010 DS: 0000 ES: 0000 CR0: 0000000080050033<br />
kernel: CR2: 0000000000000000 CR3: 00000007c6456000 CR4: 00000000001406e0<br />
kernel: Call Trace:<br />
'''kernel: do_one_initcall+0x50/0x190''' [4]<br />
kernel: ? do_init_module+0x27/0x1f2<br />
kernel: do_init_module+0x5f/0x1f2<br />
kernel: load_module+0x23f3/0x2be0<br />
kernel: SYSC_init_module+0x16b/0x1a0<br />
kernel: ? SYSC_init_module+0x16b/0x1a0<br />
kernel: SyS_init_module+0xe/0x10<br />
kernel: entry_SYSCALL_64_fastpath+0x1a/0xa5<br />
kernel: RIP: 0033:0x7f301f3a2a0a<br />
kernel: RSP: 002b:00007ffcabbd1998 EFLAGS: 00000246 ORIG_RAX: 00000000000000af<br />
kernel: RAX: ffffffffffffffda RBX: 0000000000c85a48 RCX: 00007f301f3a2a0a<br />
kernel: RDX: 000000000041aada RSI: 000000000001a738 RDI: 00007f301e7eb010<br />
kernel: RBP: 0000000000c8a520 R08: 0000000000000001 R09: 0000000000000085<br />
kernel: R10: 0000000000000000 R11: 0000000000000246 R12: 0000000000c79208<br />
kernel: R13: 0000000000c8b4d8 R14: 00007f301e7fffff R15: 0000000000000030<br />
kernel: Code: <c7> 04 25 00 00 00 00 01 00 00 00 bb f4 ff ff ff e8 73 43 9c ec 48<br />
kernel: RIP: fw_core_init+0x18/0x1000 [firewire_core] RSP: ffffb53b8db37c68<br />
kernel: CR2: 0000000000000000<br />
kernel: ---[ end trace 71f4306ea1238f17 ]---<br />
'''kernel: Kernel panic - not syncing: Fatal exception''' [5]<br />
kernel: Kernel Offset: 0x80000000 from 0xffffffff810000000 (relocation range: 0xffffffff800000000-0xfffffffffbffffffff<br />
kernel: ---[ end Kernel panic - not syncing: Fatal exception}}<br />
<br />
* [1] Indicates the type of error that caused the panic. In this case it was a programmer bug.<br />
* [2] Indicates that the panic happened in a function called ''fw_core_init'' in module ''firewire_core''.<br />
* [3] Indicates that ''firewire_core'' was the latest module to be loaded.<br />
* [4] Indicates that the function that called function ''fw_core_init'' was ''do_one_initcall''.<br />
* [5] Indicates that this ''oops'' message is, in fact, a kernel panic and the system is now deadlocked.<br />
<br />
We can surmise then, that the panic occurred during the initialization routine of module ''firewire_core'' as it was loaded. (We might assume then, that the machine's firewire hardware is incompatible with this version of the firewire driver module due to a programmer error, and will have to wait for a new release.) In the meantime, the easiest way to get the machine running again is to prevent the module from being loaded. We can do this in one of two ways:<br />
<br />
* If the module is being loaded during the execution of the ''initramfs'', reboot with the kernel parameter {{ic|1=rd.blacklist=firewire_core}}.<br />
* Otherwise reboot with the kernel parameter {{ic|1=module_blacklist=firewire_core}}.<br />
<br />
=== Reboot into root shell and fix problem ===<br />
<br />
{{Out of date|{{ic|rd.rescue}} and {{ic|rd.emergency}} will not work since [https://github.com/archlinux/svntogit-packages/commit/776743d220cbb56e9abca2cc8bcef3a0ab7c8d0a the root account in the initrmafs is locked].}}<br />
<br />
{{Accuracy|The keyboard does not work in {{ic|rd.emergency}} so it cannot be used.}}<br />
<br />
You will need a root shell to make changes to the system so the panic no longer occurs. If the panic occurs on boot, there are several strategies to obtain a root shell before the machine deadlocks:<br />
<br />
* Reboot with the kernel parameter {{ic|emergency}}, {{ic|rd.emergency}}, or {{ic|-b}} to receive a prompt to login just after the root filesystem is mounted and {{ic|systemd}} is started.<br />
: {{Note|At this point, the root filesystem will be mounted '''read-only'''. Execute {{ic|mount -o remount,rw /}} as the root user to make changes.}}<br />
* Reboot with the kernel parameter {{ic|rescue}}, {{ic|rd.rescue}}, {{ic|single}}, {{ic|s}}, {{ic|S}}, or {{ic|1}} to receive a prompt to login just after local filesystems are mounted.<br />
* Reboot with the kernel parameter {{ic|1=systemd.debug_shell}} to obtain a very early root shell on tty9. Switch to it with by pressing {{ic|Ctrl+Alt+F9}}.<br />
* Experiment by rebooting with different sets of kernel parameters to possibly disable the kernel feature that is causing the panic. Try the "old standbys" {{ic|1=acpi=off}} and {{ic|nolapic}}.<br />
: {{Tip|See [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel-parameters.html] for all kernel parameters.}}<br />
* As a last resort, boot with the '''Arch Linux Installation CD''' and mount the root filesystem on {{ic|/mnt}} then execute {{ic|arch-chroot /mnt}} as the root user.<br />
* Disable the service or program that is causing the panic, roll-back a faulty update, or fix a configuration problem.<br />
<br />
{{Tip|It may be necessary to generate a new [[Wikipedia:Initial ramdisk|initial ramdisk]] image if the original became corrupted. This can occur when a kernel update is interrupted. For creating a new one, see [[Mkinitcpio#Image creation and activation|mkinitcpio]].}}<br />
<br />
== Package management ==<br />
<br />
See [[Pacman#Troubleshooting]] for general topics, and [[pacman/Package signing#Troubleshooting]] for issues with PGP keys.<br />
<br />
=== Fixing a broken system ===<br />
<br />
<br />
If a [[partial upgrade]] was performed, try updating your whole system. A reboot may be required.<br />
<br />
# pacman -Syu<br />
<br />
If you usually boot into a GUI and that is failing, perhaps you can press {{ic|Ctrl+Alt+F1}} through {{ic|Ctrl+Alt+F6}} and get to a working tty to run ''pacman'' through.<br />
<br />
If the system is broken enough that you are unable to run ''pacman'',<br />
[[Installation_guide#Pre-installation|boot using a monthly Arch ISO from a USB flash drive, an optical disc or a network with PXE]]. (Do not follow any of the rest of the installation guide.)<br />
<br />
Mount your root filesystem:<br />
<br />
[ISO] # mount /dev/''rootFilesystemDevice'' /mnt<br />
<br />
Mount any other partitions that you created separately, adding the prefix {{ic|/mnt}} to all of them, i.e.:<br />
<br />
[ISO] # mount /dev/''bootDevice'' /mnt/boot<br />
<br />
Try using your system's ''pacman'':<br />
<br />
[ISO] # arch-chroot /mnt<br />
[chroot] # pacman -Syu<br />
<br />
If that fails, exit the ''chroot'', and try:<br />
<br />
[ISO] # pacman -Syu --sysroot /mnt<br />
<br />
If that fails, try:<br />
<br />
[ISO] # pacman -Syu --root /mnt --cachedir /mnt/var/cache/pacman/pkg<br />
<br />
== IRC collaborative debugging ==<br />
<br />
{{Move|IRC|More appropriate in the other article|section=Moving the IRC collaborative debugging section}}<br />
<br />
When requesting help from an IRC help channel (like [[Irc|#archlinux]]), it is inappropriate to paste logs into the channel and this may even get you kicked. Use a pastebin instead, you can use [[phrik]]s factoid {{ic|!paste}} to see which pastebins are acceptable.<br />
Acceptable pastebins usually work without enabling Javascript. Some require enabling Javascript for posting from a web browser, which is still acceptable because it does not affect the viewer. They should not display advertising or other disrupting content and should also not require a login. Excellent pastebins usually provide a way to paste output via piping.<br />
<br />
An example list of acceptable pastebins:<br />
<br />
* https://0x0.st - supports pasting of almost any filetype. May have slightly broken MIME type detection.<br />
* https://paste.rs - supports pasting of images, but MIME type will be off.<br />
* https://bpa.st - good for people who want something graphical.<br />
* http://ix.io - http-only. Popular, but it is useful when debugging an SSL issue which means that https-only pastebins can not be used.<br />
<br />
=== IRC usage ===<br />
<br />
{{Warning|Keep in mind that all people you encounter in the [[Arch IRC channels]] are volunteers. Be nice to them if you want to receive any help.}}<br />
<br />
When first entering the channel, [https://www.nohello.com/ there is no need to say hello]. State the problem you are experiencing and make sure to be verbose and to provide logfiles. It also helps to search for any error messages you are getting first to not waste anybodys time. It is also worth it to search for issues on any of the bugtrackers of the relevant software.<br />
The more helpful and verbose you are, the quicker you are going to receive help.<br />
<br />
If this is a problem or question which is very specific to a specific software, consider visiting the dedicated IRC channel for it if there is one. It is more likely to receive a good answer there.<br />
<br />
=== Output errors/messages to a file ===<br />
<br />
Sometimes it is not possible to pipe the output to a pastebin directly and it should be written into a file before.<br />
<br />
$ ''application'' &> ''application''-output.txt<br />
<br />
This is useful if pasting logs that contain sensitive data, e.g serial numbers in [[smartctl]] output, which have to be manually edited out.<br />
<br />
== fuser ==<br />
<br />
{{Expansion|Needs more information about its usage}}<br />
<br />
''fuser'' is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.<br />
<br />
''fuser'' is provided by the {{Pkg|psmisc}} package, which should be already installed as a dependency of the {{Pkg|base}} [[meta package]]. See {{man|1|fuser}} for details.<br />
<br />
== Session permissions ==<br />
<br />
{{Note|You must be using [[systemd]] as your init system for local sessions to work.[https://archlinux.org/news/d-bus-now-launches-user-buses/] It is required for polkit permissions and ACLs for various devices (see {{ic|/usr/lib/udev/rules.d/70-uaccess.rules}} and [https://enotty.pipebreaker.pl/2012/05/23/linux-automatic-user-acl-management/])}}<br />
<br />
First, make sure you have a valid local session within X:<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
This should contain {{ic|1=Remote=no}} and {{ic|1=Active=yes}} in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session.<br />
<br />
Basic [[polkit]] actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See [[polkit#Authentication agents]] for more information on this.<br />
<br />
== Message: "error while loading shared libraries" ==<br />
<br />
{{Accuracy|Or the program needs to be rebuilt after a [[System_maintenance#Partial_upgrades_are_unsupported|soname bump]].}}<br />
<br />
If, while using a program, you get an error similar to:<br />
<br />
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory<br />
<br />
Use [[pacman]] or [[pkgfile]] to search for the package that owns the missing library:<br />
<br />
{{hc|$ pacman -F libusb-0.1.so.4|<br />
extra/libusb-compat 0.1.5-1<br />
usr/lib/libusb-0.1.so.4<br />
}}<br />
<br />
In this case, the {{Pkg|libusb-compat}} package needs to be [[install]]ed.<br />
<br />
The error could also mean that the package that you used to install your program does not list the library as a dependency in its [[PKGBUILD]]: if it is an official package, [[report a bug]]; if it is an [[AUR]] package, report it to the maintainer using its page in the AUR website.<br />
<br />
== See also ==<br />
<br />
* [https://www.reddit.com/r/archlinux/comments/tjjwr/archlinux_a_howto_in_troubleshooting_for_newcomers/ A how-to in troubleshooting for newcomers]<br />
* [https://wiki.ultimatebootcd.com/index.php?title=Tools List of Tools for UBCD] - Memtest-like tools to add to grub.cfg on UltimateBootCD.com<br />
* [[Wikipedia:BIOS Boot partition]]<br />
* [[REISUB]]<br />
* [https://freedesktop.org/wiki/Software/systemd/Debugging/#Debug_Logging_to_a_Serial_Console Debug Logging to a Serial Console] on Freedesktop.org<br />
* [https://web.archive.org/web/20120217124742/http://www.lesswatts.org/projects/acpi/debug.php How to Isolate Linux ACPI Issues] on Archive.org</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=General_troubleshooting&diff=685427General troubleshooting2021-07-05T03:15:32Z<p>Thiagowfx: /* Additional support */ fix typo</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:System recovery]]<br />
[[Category:Installation process]]<br />
[[es:General troubleshooting]]<br />
[[fr:General troubleshooting]]<br />
[[ja:一般的なトラブルシューティング]]<br />
[[ru:General troubleshooting]]<br />
[[zh-hans:General troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debugging/Getting traces}}<br />
{{Related articles end}}<br />
<br />
This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.<br />
<br />
== General procedures ==<br />
<br />
It is crucial to ''always'' read any error messages that appear. Sometimes it may be hard, e.g with graphical applications, to get a proper error message.<br />
<br />
# Run the application in a terminal so it is possible to inspect the output.<br />
## Increase the verbosity (usually {{ic|--verbose}}/{{ic|-v}}/{{ic|-V}} or {{ic|--debug}}/{{ic|-d}}) if there is still not enough information to debug.<br />
## Sometimes there is no such parameter and it needs to be specified as a directive in the applications' configuration file.<br />
## An application may also use log files, which are usually located in {{ic|/var/log}}, {{ic|$HOME/.cache}} or {{ic|$HOME/.local}}<br />
## If there is no way to increase the verbosity, it is always possible to run [[strace]] and similar.<br />
# Check the [[journal]]. It is possible that an error may also leave traces in the journal, especially if it depends on other applications.<br />
## {{ic|dmesg}} reads from the kernel ring buffer. This is useful if the disk is for some reason inaccessible but this may also result in incomplete logs because the kernel ring buffer is not infinite in size. Use {{ic|journalctl}} if possible.<br />
## {{ic|journalctl}} has more filtering options than {{ic|dmesg}} and uses human-readable timestamps by default.<br />
# It is always recommended to check the relevant issue trackers to see if there are known issues with already existing solutions.<br />
## Depending on upstreams' choices, there is usually an issue tracker and sometimes also a forum or even e.g an IRC channel.<br />
## There is the [https://bugs.archlinux.org Arch Linux bugtracker], which should be primarily used for packaging bugs.<br />
<br />
=== Additional support ===<br />
<br />
If you require any additional support, you may ask on [https://bbs.archlinux.org the forums] or on [[IRC]].<br />
<br />
{{Note|[[Code of conduct#arch-linux-distribution-support-only|Support is provided for Arch Linux ONLY]] and not [[Arch-based distributions]].}}<br />
<br />
When asking for support post the '''complete''' output/logs, not just what you think are the significant sections. Sources of information include:<br />
<br />
* Full output of any command involved - do not just select what you think is relevant.<br />
* systemd's [[journal]].<br />
** For more extensive output, use the {{ic|1=systemd.log_level=debug}} boot parameter. This will produce a tremendous amount of output, so only enable it if it really needed.<br />
** Do not use the {{ic|-x}} parameter because this needlessly clutters the output and makes it harder to read.<br />
** Use {{ic|-b}} unless you need logs from a previous boot. Not specifying this may lead to extremely large pastes and may even be to big for any pastebins.<br />
* Relevant configuration files<br />
* Drivers involved<br />
* Versions of packages involved<br />
* Kernel: {{ic|journalctl -k}} or {{ic|dmesg}} (both with root privileges).<br />
* [[Xorg]]: depending on the setup the [[display manager]] in use is relevant here, too.<br />
** {{ic|Xorg.log}} may be located in one of several places: the system journal, {{ic|/var/log/}} or {{ic|$HOME/.local/share/xorg/}}.<br />
** Some display managers like [[LightDM]] may also place the {{ic|Xorg.log}} in its own log directory.<br />
* [[Pacman]]: If a recent upgrade broke something, look in {{ic|/var/log/pacman.log}}.<br />
** It may be useful to use pacman's {{ic|--debug}} parameter.<br />
<br />
One of the better ways to post this information is to use a [[#IRC collaborative debugging|pastebin]].<br />
<br />
A link will then be output that you can paste to the forum or IRC.<br />
<br />
Additionally, you may wish to review [https://www.co.kerr.tx.us/it/howtoreport.html how to properly report issues] before asking.<br />
<br />
== Boot problems ==<br />
<br />
When diagnosing boot problems, it is very important to know in which stage the boot fails.<br />
<br />
# BIOS/Firmware<br />
## Usually only has very basic tools for debugging.<br />
## Make sure [[Secure Boot]] is disabled.<br />
# [[Bootloader]]<br />
## One of the most common things done here is the changing of kernel parameters.<br />
# [[Initramfs]]<br />
## Usually provides an emergency shell.<br />
## Depending on the hooks chosen, either the dmesg or the journal is available within it.<br />
# The actual system<br />
## Depending on how badly it is broken, a simple invocation of the [[#Recovery shells|debug shell]] may suffice here.<br />
<br />
Unfortunately, the debugging tools provided by any stage may not be enough to fix the broken component. The [[archiso]] may be used to recover in this case.<br />
<br />
=== Console messages ===<br />
<br />
After the boot process, the screen is cleared and the login prompt appears, leaving users unable to read init output and error messages. This default behavior may be modified using methods outlined in the sections below.<br />
<br />
Note that regardless of the chosen option, kernel messages can be displayed for inspection after booting by using {{ic|journalctl -k}} or {{ic|dmesg}}. To display all logs from the current boot use {{ic|journalctl -b}}.<br />
<br />
==== Flow control ====<br />
<br />
This is basic management that applies to most terminal emulators, including virtual consoles (vc):<br />
<br />
* Press {{ic|Ctrl+s}} to pause the output<br />
* And {{ic|Ctrl+q}} to resume it<br />
<br />
This pauses not only the output, but also programs which try to print to the terminal, as they will block on the {{ic|write()}} calls for as long as the output is paused. If your ''init'' appears frozen, make sure the system console is not paused.<br />
<br />
To see error messages which are already displayed, see [[Getty#Have boot messages stay on tty1]].<br />
<br />
==== Debug output ====<br />
<br />
Most kernel messages are hidden during boot. You can see more of these messages by adding different kernel parameters. The simplest ones are:<br />
<br />
* {{ic|debug}} enables debug messages for both the kernel and [[systemd]]<br />
* {{ic|ignore_loglevel}} forces ''all'' kernel messages to be printed<br />
<br />
Other parameters you can add that might be useful in certain situations are:<br />
* {{ic|1=earlyprintk=vga,keep}} prints kernel messages very early in the boot process, in case the kernel would crash before output is shown. You must change {{ic|vga}} to {{ic|efi}} for [[EFI]] systems<br />
* {{ic|1=log_buf_len=16M}} allocates a larger (16 MiB) kernel message buffer, to ensure that debug output is not overwritten<br />
<br />
There are also a number of separate debug parameters for enabling debugging in specific subsystems e.g. {{ic|bootmem_debug}}, {{ic|sched_debug}}. Also, {{ic|initcall_debug}} can be useful to investigate boot freezes. (Look for calls that did not return.) Check the [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel parameter documentation] for specific information.<br />
<br />
==== netconsole ====<br />
<br />
[https://www.kernel.org/doc/html/latest/networking/netconsole.html netconsole] is a kernel module that sends all kernel log messages (i.e. dmesg) over the network to another computer, without involving user space (e.g. syslogd). Name "netconsole" is a misnomer because it is not really a "console", more like a remote logging service.<br />
<br />
It can be used either built-in or as a module. Built-in ''netconsole'' initializes immediately after NIC cards and will bring up the specified interface as soon as possible. The module is mainly used for capturing kernel panic output from a headless machine, or in other situations where the user space is no more functional.<br />
<br />
=== Recovery shells ===<br />
<br />
Getting an interactive shell at some stage in the boot process can help you pinpoint exactly where and why something is failing. There are several kernel parameters for doing so, but they all launch a normal shell which you can {{ic|exit}} to let the kernel resume what it was doing:<br />
* {{ic|rescue}} launches a shell shortly after the root filesystem is remounted read/write<br />
* {{ic|emergency}} launches a shell even earlier, before most filesystems are mounted<br />
* {{ic|1=init=/bin/sh}} (as a last resort) changes the init program to a root shell. {{ic|rescue}} and {{ic|emergency}} both rely on [[systemd]], but this should work even if ''systemd'' is broken<br />
<br />
Another option is systemd's debug-shell which adds a root shell on {{ic|tty9}} (accessible with {{ic|Ctrl+Alt+F9}}). It can be enabled by either adding {{ic|systemd.debug_shell}} to the [[kernel parameters]], or by [[enabling]] {{ic|debug-shell.service}}.<br />
<br />
{{Warning|Remember to disable the service when done to avoid the security risk of leaving a root shell open on every boot.}}<br />
<br />
=== Debugging kernel modules ===<br />
<br />
See [[Kernel modules#Obtaining information]].<br />
<br />
=== Debugging hardware ===<br />
<br />
* You can display extra debugging information about your hardware by following [[udev#Debug output]].<br />
* Ensure that [[Microcode]] updates are applied on your system.<br />
* To test the RAM, see [[Stress testing#Stressing memory]].<br />
<br />
== Debugging freezes ==<br />
<br />
Unfortunately, freezes are usually hard to debug and some of them take a lot of time to reproduce. There are some types of freezes which are easier to debug than others:<br />
<br />
* Is sound still playing? If so, just the display may be frozen. This may be a problem with the video driver.<br />
* Is the machine still responding? Try [[SSH]] if switching to another [[Tty|TTY]] does not work.<br />
* Is the disk activity LED (if present) indicating that a lot is being written to disk? Heavy swapping may temporarily freeze the system. See [https://unix.stackexchange.com/a/340567 this StackExchange answer] for information about freezes on large writes.<br />
<br />
If nothing else helps, try a '''clean''' shutdown. Pressing the power button ''once'' may unfreeze the system and show the classic "shutdown screen" which displays all the units that are getting stopped. Alternatively, using the magic [[SysRq]] keys may also help to achieve a clean shutdown. This is very important because the [[journal]] may contain hints why the machine froze. The journal may not be written to disk on an unclean shutdown. Hard freezes in which the whole machine is unresponsible are harder to debug since logs can not be written to disk in time.<br />
<br />
Remote logging may help if the freeze does not permit writing anything to disk. A crude remote logging solution, which needs to be invoked from another device, can be used for basic debugging:<br />
<br />
$ ssh ''freezing host'' journalctl -f<br />
<br />
Many fatal freezes in which the whole system does not respond anymore and require a forced shutdown may be related to buggy firmware, drivers or hardware. Trying a different kernel (see [[Kernel#Debugging regressions]]) or even a different Linux distribution or operating system, updating the firmware and running hardware diagnostics may help finding the problem.<br />
<br />
{{Tip|It is recommended to try to update the firmware of the device, since these updates may fix strange issues.}}<br />
<br />
If a freeze does not permit gathering any kind of logs or other information required for debugging, try reproducing the freeze in a live environment. If a graphical environment is required to reproduce the freeze or if the freeze can be reproduced on the archiso, use the live environment of a different distribution, which is preferably not based on Arch Linux to eliminate the possibility that the freeze is related to the version or patches of the kernel.<br />
Should the freeze still happen in a live environment, chances are that it ''may'' be hardware-related. If it does not happen anymore, it is necessary to be aware of the differences of both systems. Different configurations, differences in versions and kernel parameters and other, similar changes may have fixed the freeze.<br />
<br />
However, a blinking caps lock LED may indicate a [[kernel panic]]. Some setups may not show the TTY when a kernel panic occurred, which may be confusing and can be interpreted as another kind of freeze.<br />
<br />
== Debugging regressions ==<br />
<br />
If an update causes an issue but [[downgrading]] the specific package fixes it, it is likely a [[wikipedia:Software regression|regression]]. The most important part of debugging regressions is checking if the issue was already fixed, as this can save much time. To do so, first ensure the application is fully updated (e.g ensure the application is the same version as in the [[official repositories]]). If it already is or if updating it does not fix the issue, try using the the actual latest version, usually a [[Arch User Repository#What is the difference between foo and foo-git packages?|-git]] version, which are may be already packaged in the [[AUR]]. If this fixes the issue and the version with the fixes is not yet in the official repositories, wait until the new version arrives in them and then switch back to it.<br />
<br />
If the issue still persists, debug the issue and/or [[bisect]] the application and report the bug on the upstream bugtracker so it can be fixed.<br />
<br />
{{Note|The kernel needs a [[Kernel#Debugging regressions|slightly different approach]] when debugging regressions.}}<br />
<br />
== Kernel panics ==<br />
<br />
A ''kernel panic'' occurs when the Linux kernel enters an unrecoverable failure state. The state typically originates from buggy hardware drivers resulting in the machine being deadlocked, non-responsive, and requiring a reboot. Just prior to deadlock, a diagnostic message is generated, consisting of: the ''machine state'' when the failure occurred, a ''call trace'' leading to the kernel function that recognized the failure, and a listing of currently loaded modules. Thankfully, kernel panics do not happen very often using ''mainline'' versions of the kernel--such as those supplied by the official repositories--but when they do happen, you need to know how to deal with them.<br />
<br />
{{Note|Kernel panics are sometimes referred to as ''oops'' or ''kernel oops''. While both panics and oops occur as the result of a failure state, an ''oops'' is more general in that it does not ''necessarily'' result in a deadlocked machine--sometimes the kernel can recover from an oops by killing the offending task and carrying on.}}<br />
<br />
{{Tip|Pass the kernel parameter {{ic|1=oops=panic}} at boot or write {{ic|1}} to {{ic|/proc/sys/kernel/panic_on_oops}} to force a recoverable oops to issue a panic instead. This is advisable if you are concerned about the small chance of system instability resulting from an oops recovery which may make future errors difficult to diagnose.}}<br />
<br />
=== Examine panic message ===<br />
<br />
If a kernel panic occurs very early in the boot process, you may see a message on the console containing "Kernel panic - not syncing:", but once [[Systemd]] is running, kernel messages will typically be captured and written to the system log. However, when a panic occurs, the diagnostic message output by the kernel is ''almost never'' written to the log file on disk because the machine deadlocks before {{ic|system-journald}} gets the chance. Therefore, the only way to examine the panic message is to view it on the console as it happens (without resorting to setting up a ''kdump crashkernel''). You can do this by booting with the following kernel parameters and attempting to reproduce the panic on tty1:<br />
<br />
{{bc|1=systemd.journald.forward_to_console=1 console=tty1}}<br />
<br />
{{Tip|In the event that the panic message scrolls away too quickly to examine, try passing the kernel parameter {{ic|1=pause_on_oops=''seconds''}} at boot.}}<br />
<br />
==== Example scenario: bad module ====<br />
<br />
It is possible to make a best guess as to what subsystem or module is causing the panic using the information in the diagnostic message. In this scenario, we have a panic on some imaginary machine during boot. Pay attention to the lines highlighted in '''bold''':<br />
<br />
{{bc|'''kernel: BUG: unable to handle kernel NULL pointer dereference at (null)''' [1]<br />
'''kernel: IP: fw_core_init+0x18/0x1000 [firewire_core]''' [2]<br />
kernel: PGD 718d00067<br />
kernel: P4D 718d00067<br />
kernel: PUD 7b3611067<br />
kernel: PMD 0<br />
kernel:<br />
kernel: Oops: 0002 [#1] PREEMPT SMP<br />
'''kernel: Modules linked in: firewire_core(+) crc_itu_t cfg80211 rfkill ipt_REJECT nf_reject_ipv4 nf_log_ipv4 nf_log_common xt_LOG nf_conntrack_ipv4 ...''' [3]<br />
kernel: CPU: 6 PID: 1438 Comm: modprobe Tainted: P O 4.13.3-1-ARCH #1<br />
kernel: Hardware name: Gigabyte Technology Co., Ltd. H97-D3H/H97-D3H-CF, BIOS F5 06/26/2014<br />
kernel: task: ffff9c667abd9e00 task.stack: ffffb53b8db34000<br />
kernel: RIP: 0010:fw_core_init+0x18/0x1000 [firewire_core]<br />
kernel: RSP: 0018:ffffb53b8db37c68 EFLAGS: 00010246<br />
kernel: RAX: 0000000000000000 RBX: 0000000000000000 RCX: 0000000000000000<br />
kernel: RDX: 0000000000000000 RSI: 0000000000000008 RDI: ffffffffc16d3af4<br />
kernel: RBP: ffffb53b8db37c70 R08: 0000000000000000 R09: ffffffffae113e95<br />
kernel: R10: ffffe93edfdb9680 R11: 0000000000000000 R12: ffffffffc16d9000<br />
kernel: R13: ffff9c6729bf8f60 R14: ffffffffc16d5710 R15: ffff9c6736e55840<br />
kernel: FS: 00007f301fc80b80(0000) GS:ffff9c675dd80000(0000) knlGS:0000000000000000<br />
kernel: CS: 0010 DS: 0000 ES: 0000 CR0: 0000000080050033<br />
kernel: CR2: 0000000000000000 CR3: 00000007c6456000 CR4: 00000000001406e0<br />
kernel: Call Trace:<br />
'''kernel: do_one_initcall+0x50/0x190''' [4]<br />
kernel: ? do_init_module+0x27/0x1f2<br />
kernel: do_init_module+0x5f/0x1f2<br />
kernel: load_module+0x23f3/0x2be0<br />
kernel: SYSC_init_module+0x16b/0x1a0<br />
kernel: ? SYSC_init_module+0x16b/0x1a0<br />
kernel: SyS_init_module+0xe/0x10<br />
kernel: entry_SYSCALL_64_fastpath+0x1a/0xa5<br />
kernel: RIP: 0033:0x7f301f3a2a0a<br />
kernel: RSP: 002b:00007ffcabbd1998 EFLAGS: 00000246 ORIG_RAX: 00000000000000af<br />
kernel: RAX: ffffffffffffffda RBX: 0000000000c85a48 RCX: 00007f301f3a2a0a<br />
kernel: RDX: 000000000041aada RSI: 000000000001a738 RDI: 00007f301e7eb010<br />
kernel: RBP: 0000000000c8a520 R08: 0000000000000001 R09: 0000000000000085<br />
kernel: R10: 0000000000000000 R11: 0000000000000246 R12: 0000000000c79208<br />
kernel: R13: 0000000000c8b4d8 R14: 00007f301e7fffff R15: 0000000000000030<br />
kernel: Code: <c7> 04 25 00 00 00 00 01 00 00 00 bb f4 ff ff ff e8 73 43 9c ec 48<br />
kernel: RIP: fw_core_init+0x18/0x1000 [firewire_core] RSP: ffffb53b8db37c68<br />
kernel: CR2: 0000000000000000<br />
kernel: ---[ end trace 71f4306ea1238f17 ]---<br />
'''kernel: Kernel panic - not syncing: Fatal exception''' [5]<br />
kernel: Kernel Offset: 0x80000000 from 0xffffffff810000000 (relocation range: 0xffffffff800000000-0xfffffffffbffffffff<br />
kernel: ---[ end Kernel panic - not syncing: Fatal exception}}<br />
<br />
* [1] Indicates the type of error that caused the panic. In this case it was a programmer bug.<br />
* [2] Indicates that the panic happened in a function called ''fw_core_init'' in module ''firewire_core''.<br />
* [3] Indicates that ''firewire_core'' was the latest module to be loaded.<br />
* [4] Indicates that the function that called function ''fw_core_init'' was ''do_one_initcall''.<br />
* [5] Indicates that this ''oops'' message is, in fact, a kernel panic and the system is now deadlocked.<br />
<br />
We can surmise then, that the panic occurred during the initialization routine of module ''firewire_core'' as it was loaded. (We might assume then, that the machine's firewire hardware is incompatible with this version of the firewire driver module due to a programmer error, and will have to wait for a new release.) In the meantime, the easiest way to get the machine running again is to prevent the module from being loaded. We can do this in one of two ways:<br />
<br />
* If the module is being loaded during the execution of the ''initramfs'', reboot with the kernel parameter {{ic|1=rd.blacklist=firewire_core}}.<br />
* Otherwise reboot with the kernel parameter {{ic|1=module_blacklist=firewire_core}}.<br />
<br />
=== Reboot into root shell and fix problem ===<br />
<br />
{{Out of date|{{ic|rd.rescue}} and {{ic|rd.emergency}} will not work since [https://github.com/archlinux/svntogit-packages/commit/776743d220cbb56e9abca2cc8bcef3a0ab7c8d0a the root account in the initrmafs is locked].}}<br />
<br />
{{Accuracy|The keyboard does not work in {{ic|rd.emergency}} so it cannot be used.}}<br />
<br />
You will need a root shell to make changes to the system so the panic no longer occurs. If the panic occurs on boot, there are several strategies to obtain a root shell before the machine deadlocks:<br />
<br />
* Reboot with the kernel parameter {{ic|emergency}}, {{ic|rd.emergency}}, or {{ic|-b}} to receive a prompt to login just after the root filesystem is mounted and {{ic|systemd}} is started.<br />
: {{Note|At this point, the root filesystem will be mounted '''read-only'''. Execute {{ic|mount -o remount,rw /}} as the root user to make changes.}}<br />
* Reboot with the kernel parameter {{ic|rescue}}, {{ic|rd.rescue}}, {{ic|single}}, {{ic|s}}, {{ic|S}}, or {{ic|1}} to receive a prompt to login just after local filesystems are mounted.<br />
* Reboot with the kernel parameter {{ic|1=systemd.debug_shell}} to obtain a very early root shell on tty9. Switch to it with by pressing {{ic|Ctrl+Alt+F9}}.<br />
* Experiment by rebooting with different sets of kernel parameters to possibly disable the kernel feature that is causing the panic. Try the "old standbys" {{ic|1=acpi=off}} and {{ic|nolapic}}.<br />
: {{Tip|See [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel-parameters.html] for all kernel parameters.}}<br />
* As a last resort, boot with the '''Arch Linux Installation CD''' and mount the root filesystem on {{ic|/mnt}} then execute {{ic|arch-chroot /mnt}} as the root user.<br />
* Disable the service or program that is causing the panic, roll-back a faulty update, or fix a configuration problem.<br />
<br />
{{Tip|It may be necessary to generate a new [[Wikipedia:Initial ramdisk|initial ramdisk]] image if the original became corrupted. This can occur when a kernel update is interrupted. For creating a new one, see [[Mkinitcpio#Image creation and activation|mkinitcpio]].}}<br />
<br />
== Package management ==<br />
<br />
See [[Pacman#Troubleshooting]] for general topics, and [[pacman/Package signing#Troubleshooting]] for issues with PGP keys.<br />
<br />
=== Fixing a broken system ===<br />
<br />
<br />
If a [[partial upgrade]] was performed, try updating your whole system. A reboot may be required.<br />
<br />
# pacman -Syu<br />
<br />
If you usually boot into a GUI and that is failing, perhaps you can press {{ic|Ctrl+Alt+F1}} through {{ic|Ctrl+Alt+F6}} and get to a working tty to run ''pacman'' through.<br />
<br />
If the system is broken enough that you are unable to run ''pacman'',<br />
[[Installation_guide#Pre-installation|boot using a monthly Arch ISO from a USB flash drive, an optical disc or a network with PXE]]. (Do not follow any of the rest of the installation guide.)<br />
<br />
Mount your root filesystem:<br />
<br />
[ISO] # mount /dev/''rootFilesystemDevice'' /mnt<br />
<br />
Mount any other partitions that you created separately, adding the prefix {{ic|/mnt}} to all of them, i.e.:<br />
<br />
[ISO] # mount /dev/''bootDevice'' /mnt/boot<br />
<br />
Try using your system's ''pacman'':<br />
<br />
[ISO] # arch-chroot /mnt<br />
[chroot] # pacman -Syu<br />
<br />
If that fails, exit the ''chroot'', and try:<br />
<br />
[ISO] # pacman -Syu --sysroot /mnt<br />
<br />
If that fails, try:<br />
<br />
[ISO] # pacman -Syu --root /mnt --cachedir /mnt/var/cache/pacman/pkg<br />
<br />
== IRC collaborative debugging ==<br />
<br />
{{Move|IRC|More appropriate in the other article|section=Moving the IRC collaborative debugging section}}<br />
<br />
When requesting help from an IRC help channel (like [[Irc|#archlinux]]), it is inappropriate to paste logs into the channel and this may even get you kicked. Use a pastebin instead, you can use [[phrik]]s factoid {{ic|!paste}} to see which pastebins are acceptable.<br />
Acceptable pastebins usually work without enabling Javascript. Some require enabling Javascript for posting from a web browser, which is still acceptable because it does not affect the viewer. They should not display advertising or other disrupting content and should also not require a login. Excellent pastebins usually provide a way to paste output via piping.<br />
<br />
An example list of acceptable pastebins:<br />
<br />
* https://0x0.st - supports pasting of almost any filetype. May have slightly broken MIME type detection.<br />
* https://paste.rs - supports pasting of images, but MIME type will be off.<br />
* https://bpa.st - good for people who want something graphical.<br />
* http://ix.io - http-only. Popular, but it is useful when debugging an SSL issue which means that https-only pastebins can not be used.<br />
<br />
=== IRC usage ===<br />
<br />
{{Warning|Keep in mind that all people you encounter in the [[Arch IRC channels]] are volunteers. Be nice to them if you want to receive any help.}}<br />
<br />
When first entering the channel, [https://www.nohello.com/ there is no need to say hello]. State the problem you are experiencing and make sure to be verbose and to provide logfiles. It also helps to search for any error messages you are getting first to not waste anybodys time. It is also worth it to search for issues on any of the bugtrackers of the relevant software.<br />
The more helpful and verbose you are, the quicker you are going to receive help.<br />
<br />
If this is a problem or question which is very specific to a specific software, consider visiting the dedicated IRC channel for it if there is one. It is more likely to receive a good answer there.<br />
<br />
=== Output errors/messages to a file ===<br />
<br />
Sometimes it is not possible to pipe the output to a pastebin directly and it should be written into a file before.<br />
<br />
$ ''application'' &> ''application''-output.txt<br />
<br />
This is useful if pasting logs that contain sensitive data, e.g serial numbers in [[smartctl]] output, which have to be manually edited out.<br />
<br />
== fuser ==<br />
<br />
{{Expansion|Needs more information about its usage}}<br />
<br />
''fuser'' is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.<br />
<br />
''fuser'' is provided by the {{Pkg|psmisc}} package, which should be already installed as a dependency of the {{Pkg|base}} [[meta package]]. See {{man|1|fuser}} for details.<br />
<br />
== Session permissions ==<br />
<br />
{{Note|You must be using [[systemd]] as your init system for local sessions to work.[https://archlinux.org/news/d-bus-now-launches-user-buses/] It is required for polkit permissions and ACLs for various devices (see {{ic|/usr/lib/udev/rules.d/70-uaccess.rules}} and [https://enotty.pipebreaker.pl/2012/05/23/linux-automatic-user-acl-management/])}}<br />
<br />
First, make sure you have a valid local session within X:<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
This should contain {{ic|1=Remote=no}} and {{ic|1=Active=yes}} in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session.<br />
<br />
Basic [[polkit]] actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See [[polkit#Authentication agents]] for more information on this.<br />
<br />
== Message: "error while loading shared libraries" ==<br />
<br />
{{Accuracy|Or the program needs to be rebuilt after a [[System_maintenance#Partial_upgrades_are_unsupported|soname bump]].}}<br />
<br />
If, while using a program, you get an error similar to:<br />
<br />
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory<br />
<br />
Use [[pacman]] or [[pkgfile]] to search for the package that owns the missing library:<br />
<br />
{{hc|$ pacman -F libusb-0.1.so.4|<br />
extra/libusb-compat 0.1.5-1<br />
usr/lib/libusb-0.1.so.4<br />
}}<br />
<br />
In this case, the {{Pkg|libusb-compat}} package needs to be [[install]]ed.<br />
<br />
The error could also mean that the package that you used to install your program does not list the library as a dependency in its [[PKGBUILD]]: if it is an official package, [[report a bug]]; if it is an [[AUR]] package, report it to the maintainer using its page in the AUR website.<br />
<br />
== See also ==<br />
<br />
* [https://www.reddit.com/r/archlinux/comments/tjjwr/archlinux_a_howto_in_troubleshooting_for_newcomers/ A how-to in troubleshooting for newcomers]<br />
* [https://wiki.ultimatebootcd.com/index.php?title=Tools List of Tools for UBCD] - Memtest-like tools to add to grub.cfg on UltimateBootCD.com<br />
* [[Wikipedia:BIOS Boot partition]]<br />
* [[REISUB]]<br />
* [https://freedesktop.org/wiki/Software/systemd/Debugging/#Debug_Logging_to_a_Serial_Console Debug Logging to a Serial Console] on Freedesktop.org<br />
* [https://web.archive.org/web/20120217124742/http://www.lesswatts.org/projects/acpi/debug.php How to Isolate Linux ACPI Issues] on Archive.org</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=XDG_Autostart&diff=685423XDG Autostart2021-07-05T02:19:27Z<p>Thiagowfx: /* Directories */ convert Hidden=true into a tip</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[es:XDG Autostart]]<br />
[[hu:XDG Autostart]]<br />
[[ja:XDG Autostart]]<br />
[[pt:XDG Autostart]]<br />
[[zh-hans:XDG Autostart]]<br />
The [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html XDG Autostart specification] defines a method for [[autostarting]] ordinary [[desktop entries]] on [[desktop environment]] startup and removable medium mounting, by placing them in specific [[#Directories]].<br />
<br />
== Prerequisites ==<br />
<br />
You need to use either a [[desktop environment]] that supports it, or a dedicated implementation, like:<br />
<br />
* {{pkg|dex}}<br />
* {{AUR|dapper}}<br />
* {{AUR|fbautostart}}<br />
* {{AUR|sandsmark-xdg-autostart-launcher-git}}<br />
<br />
== Directories ==<br />
<br />
The Autostart directories in order of preference are:<br />
<br />
* user-specific: {{ic|$XDG_CONFIG_HOME/autostart}} ({{ic|~/.config/autostart}} by default)<br />
* system-wide: {{ic|$XDG_CONFIG_DIRS/autostart}} ({{ic|/etc/xdg/autostart}} by default)[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#referencing]<br />
<br />
System-wide [[desktop entries]] can be overridden by user-specific entries with the same filename.<br />
<br />
{{Tip|To disable a system-wide entry, create an overriding entry containing {{ic|1=Hidden=true}}.}}<br />
<br />
For more details, read [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html the specification].</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=XDG_Autostart&diff=685422XDG Autostart2021-07-05T02:18:54Z<p>Thiagowfx: /* Prerequisites */ remove extra period</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[es:XDG Autostart]]<br />
[[hu:XDG Autostart]]<br />
[[ja:XDG Autostart]]<br />
[[pt:XDG Autostart]]<br />
[[zh-hans:XDG Autostart]]<br />
The [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html XDG Autostart specification] defines a method for [[autostarting]] ordinary [[desktop entries]] on [[desktop environment]] startup and removable medium mounting, by placing them in specific [[#Directories]].<br />
<br />
== Prerequisites ==<br />
<br />
You need to use either a [[desktop environment]] that supports it, or a dedicated implementation, like:<br />
<br />
* {{pkg|dex}}<br />
* {{AUR|dapper}}<br />
* {{AUR|fbautostart}}<br />
* {{AUR|sandsmark-xdg-autostart-launcher-git}}<br />
<br />
== Directories ==<br />
<br />
The Autostart directories in order of preference are:<br />
<br />
* user-specific: {{ic|$XDG_CONFIG_HOME/autostart}} ({{ic|~/.config/autostart}} by default)<br />
* system-wide: {{ic|$XDG_CONFIG_DIRS/autostart}} ({{ic|/etc/xdg/autostart}} by default)[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#referencing]<br />
<br />
System-wide [[desktop entries]] can be overridden by user-specific entries with the same filename.<br />
<br />
To disable a system-wide entry, create an overriding entry containing {{ic|1=Hidden=true}}.<br />
<br />
For more details, read [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html the specification].</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=XDG_Autostart&diff=685421XDG Autostart2021-07-05T02:18:44Z<p>Thiagowfx: /* Prerequisites */ convert apps into a bulleted list</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[es:XDG Autostart]]<br />
[[hu:XDG Autostart]]<br />
[[ja:XDG Autostart]]<br />
[[pt:XDG Autostart]]<br />
[[zh-hans:XDG Autostart]]<br />
The [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html XDG Autostart specification] defines a method for [[autostarting]] ordinary [[desktop entries]] on [[desktop environment]] startup and removable medium mounting, by placing them in specific [[#Directories]].<br />
<br />
== Prerequisites ==<br />
<br />
You need to use either a [[desktop environment]] that supports it, or a dedicated implementation, like:<br />
<br />
* {{pkg|dex}}<br />
* {{AUR|dapper}}<br />
* {{AUR|fbautostart}}<br />
* {{AUR|sandsmark-xdg-autostart-launcher-git}}.<br />
<br />
== Directories ==<br />
<br />
The Autostart directories in order of preference are:<br />
<br />
* user-specific: {{ic|$XDG_CONFIG_HOME/autostart}} ({{ic|~/.config/autostart}} by default)<br />
* system-wide: {{ic|$XDG_CONFIG_DIRS/autostart}} ({{ic|/etc/xdg/autostart}} by default)[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#referencing]<br />
<br />
System-wide [[desktop entries]] can be overridden by user-specific entries with the same filename.<br />
<br />
To disable a system-wide entry, create an overriding entry containing {{ic|1=Hidden=true}}.<br />
<br />
For more details, read [https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html the specification].</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Chromium&diff=685420Chromium2021-07-05T02:13:22Z<p>Thiagowfx: /* Chromium low scroll speed */ fix typos</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Google]]<br />
[[de:Chromium]]<br />
[[es:Chromium]]<br />
[[ja:Chromium]]<br />
[[zh-hans:Chromium]]<br />
{{Related articles start}}<br />
{{Related|Browser extensions}}<br />
{{Related|Firefox}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Chromium (web browser)|Chromium]] is an open-source graphical web browser based on the [[Wikipedia:Blink (web engine)|Blink]] rendering engine. It is the basis for the proprietary Google Chrome browser.<br />
<br />
See [https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md this page] for an explanation of the differences between Chromium and Google Chrome. Additionally:<br />
<br />
* Sync is unavailable in Chromium 89+ (2021-03-02) [https://archlinux.org/news/chromium-losing-sync-support-in-early-march/]<br />
<br />
{{Note|Sync can be temporarily restored by [https://gist.github.com/foutrelis/14e339596b89813aa9c37fd1b4e5d9d5 using Chrome's OAuth2 credentials] or [https://www.chromium.org/developers/how-tos/api-keys getting your own], but pay attention to the disclaimers and do not consider this to be a long-term solution.<br />
Consider switching to [https://xbrowsersync.org xbrowsersync] for bookmarks syncing as long term solution.<br />
}}<br />
<br />
See [[List of applications/Internet#Blink-based]] for other browsers based on Chromium.<br />
<br />
== Installation ==<br />
<br />
There are several packages available to [[install]] Chromium with:<br />
<br />
* {{Pkg|chromium}} — stable release;<br />
* {{AUR|chromium-dev}} — development release;<br />
* {{AUR|chromium-snapshot-bin}} — nightly build.<br />
<br />
Google Chrome packages:<br />
<br />
* {{AUR|google-chrome}} — stable release;<br />
* {{AUR|google-chrome-beta}} — beta release;<br />
* {{AUR|google-chrome-dev}} — development release.<br />
<br />
{{Note|From the [https://www.chromium.org/Home/chromium-privacy Chromium privacy page]: "Features that communicate with Google made available through the compilation of code in Chromium are subject to the [https://www.google.com/policies/privacy/ Google Privacy Policy]." For those who want to avoid all integration with Google services, there are some [[List of applications/Internet#Privacy-focused chromium spin-offs|privacy-focused spin-offs]].}}<br />
<br />
== Configuration ==<br />
<br />
=== Default applications ===<br />
<br />
To set Chromium as the default browser and to change which applications Chromium launches when opening downloaded files, see [[default applications]].<br />
<br />
=== Certificates ===<br />
<br />
Chromium uses [[Network Security Services]] for certificate management. Certificates can be managed in {{ic|chrome://settings/certificates}}.<br />
<br />
=== Force GPU acceleration ===<br />
<br />
{{Warning|Disabling the rendering blacklist may cause unstable behavior, including crashes of the host. See the bug reports in {{ic|chrome://gpu}} for details.}}<br />
<br />
By default Chromium on Linux does not use any GPU acceleration. To force GPU acceleration, [[append]] the following flags to [[/Tips and tricks#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
--enable-zero-copy<br />
}}<br />
<br />
Additionally the flag {{ic|--disable-gpu-driver-bug-workarounds}} may need to be passed to prevent GPU workaround from being used. Flags in {{ic|chrome://gpu}} should state "Hardware accelerated" when configured and available.<br />
<br />
{{ic|--enable-native-gpu-memory-buffers}} is broken since mesa 20.1.1 [https://gitlab.freedesktop.org/mesa/mesa/-/issues/3119#note_533902]<br />
<br />
=== Hardware video acceleration ===<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* There is no official support from Chromium or Arch Linux for this feature [https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md#vaapi-on-linux]. However, {{Pkg|chromium}} from official repositories is compiled with VA-API support and you may ask for help in [https://bbs.archlinux.org/viewtopic.php?id=244031 the dedicated forum thread].<br />
* Wayland is not supported.}}<br />
<br />
To enable VA-API support in Chromium:<br />
* Install the correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]]. For proprietary NVIDIA support, installing {{AUR|libva-vdpau-driver-chromium}} or {{AUR|libva-vdpau-driver-vp9-git}} is required.<br />
* Set the option {{ic|1=--enable-features=VaapiVideoDecoder}}. This is enough when using ANGLE GL renderer and {{Pkg|libva-intel-driver}}.<br />
* When using ANGLE, Chromium forces the older i965 driver and fails when {{Pkg|intel-media-driver}} is used. As a workaround, [[Hardware video acceleration#Configuring VA-API|configure VA-API manually]]. See [https://github.com/intel/media-driver/issues/818] for details.<br />
* To use the system GL renderer on Xorg, use either {{ic|1=--use-gl=egl}} or {{ic|1=--use-gl=desktop}}. On XWayland, use the {{ic|1=--use-gl=egl}} flag (Currently exhibits choppiness {{Bug|67035}} on some systems).<br />
<br />
==== Tips and tricks ====<br />
To check if it's working play a video which is using a codec supported by your VA-API driver (''vainfo'' tells you which codecs are supported, but Chromium will only support VP9 and h264):<br />
<br />
* Open the DevTools by pressing {{ic|Ctrl+Shift+I}} or on the ''Inspect'' button of the context (right-click) menu<br />
* Add the Media inspection tab: ''Hamburger menu > More tools > Media''<br />
* In the newly opened Media tab, look at the hardware decoder state of the video decoder<br />
<br />
Test on a large enough video. Starting with version 86, Chromium on desktop [https://bugs.chromium.org/p/chromium/issues/detail?id=684792 will only accelerate videos larger than 720p].<br />
<br />
To reduce CPU usage while watching YouTube where VP8/VP9 hardware decoding is not available use the [https://chrome.google.com/webstore/detail/h264ify/aleakchihdccplidncghkekgioiakgal h264ify] or [https://chrome.google.com/webstore/detail/enhanced-h264ify/omkfmpieigblcllmkgbflkikinpkodlk enhanced-h264ify] extension.<br />
<br />
On some systems (especially on XWayland) you might need to [[#Force GPU acceleration]]. Only {{ic|--ignore-gpu-blocklist}} is enough for our purposes.<br />
<br />
{{Expansion|Provide a link to some bug report.}}<br />
You might need to disable the Skia renderer, as it is currently not compatible with video decode acceleration: {{ic|1=--disable-features=UseSkiaRenderer}}<br />
<br />
=== Making flags persistent ===<br />
<br />
{{Note|The {{ic|chromium-flags.conf}} file and the accompanying custom launcher script are specific to the Arch Linux {{Pkg|chromium}} package. For {{AUR|google-chrome}} and {{AUR|google-chrome-dev}}, use {{ic|chrome-flags.conf}} and {{ic|chrome-dev-flags.conf}} instead.}}<br />
<br />
You can put your flags in a {{ic|chromium-flags.conf}} file under {{ic|$HOME/.config/}} (or under {{ic|$XDG_CONFIG_HOME}} if you have configured that environment variable).<br />
<br />
No special syntax is used; flags are defined as if they were written in a terminal.<br />
<br />
* The arguments are split on whitespace and shell quoting rules apply, but no further parsing is performed.<br />
* In case of improper quoting anywhere in the file, a fatal error is raised.<br />
* Flags can be placed in separate lines for readability, but this is not required.<br />
* Lines starting with a hash symbol (#) are skipped.<br />
<br />
Below is an example {{ic|chromium-flags.conf}} file that defines the flags {{ic|--start-maximized --incognito}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|<br />
# This line will be ignored.<br />
--start-maximized<br />
--incognito<br />
}}<br />
<br />
=== PDF viewer plugin ===<br />
<br />
Chromium and Google Chrome are bundled with the ''Chromium PDF Viewer'' plugin. If you do not want to use this plugin, check ''Open PDFs using a different application'' in {{ic|chrome://settings/content/pdfDocuments}}.<br />
<br />
=== Flash Player plugin ===<br />
<br />
Support for Flash Player was removed in Chromium 88.[https://www.chromium.org/flash-roadmap#TOC-Flash-Support-Removed-from-Chromium-Target:-Chrome-88---Jan-2021-]<br />
<br />
=== Native Wayland support ===<br />
<br />
Since version 87, native [[Wayland]] support in Chromium can be enabled with the following flags [https://bugs.chromium.org/p/chromium/issues/detail?id=1085700]:<br />
<br />
--enable-features=UseOzonePlatform --ozone-platform=wayland<br />
<br />
See [[#Making flags persistent]] for a permanent configuration.<br />
<br />
== Tips and tricks ==<br />
<br />
The following tips and tricks should work for both Chromium and Chrome unless explicitly stated.<br />
<br />
=== Browsing experience ===<br />
<br />
==== chrome:// URLs ====<br />
<br />
A number of tweaks can be accessed via Chrome URLs. See '''chrome://chrome-urls''' for a complete list.<br />
<br />
* '''chrome://flags''' - access experimental features such as WebGL and rendering webpages with GPU, etc.<br />
* '''chrome://extensions''' - view, enable and disable the currently used Chromium extensions.<br />
* '''chrome://gpu''' - status of different GPU options.<br />
* '''chrome://sandbox''' - indicate sandbox status.<br />
* '''chrome://version''' - display version and switches used to invoke the active {{ic|/usr/bin/chromium}}.<br />
<br />
An automatically updated, complete listing of Chromium switches (command line parameters) is available [https://peter.sh/experiments/chromium-command-line-switches/ here].<br />
<br />
==== Chromium task manager ====<br />
<br />
Shift+ESC can be used to bring up the browser task manager wherein memory, CPU, and network usage can be viewed.<br />
<br />
==== Chromium overrides/overwrites Preferences file ====<br />
<br />
If you enabled syncing with a Google Account, then Chromium will override any direct edits to the Preferences file found under {{ic|~/.config/chromium/Default/Preferences}}. To work around this, start Chromium with the {{ic|--disable-sync-preferences}} switch:<br />
$ chromium --disable-sync-preferences<br />
<br />
If Chromium is started in the background when you login in to your desktop environment, make sure the command your desktop environment uses is:<br />
$ chromium --disable-sync-preferences --no-startup-window<br />
<br />
==== Search engines ====<br />
<br />
Make sites like [https://wiki.archlinux.org wiki.archlinux.org] and [https://en.wikipedia.org wikipedia.org] easily searchable by first executing a search on those pages, then going to ''Settings > Search'' and click the ''Manage search engines..'' button. From there, "Edit" the Wikipedia entry and change its keyword to '''w''' (or some other shortcut you prefer). Now searching Wikipedia for "Arch Linux" from the address bar is done simply by entering "'''w arch linux'''".<br />
<br />
{{Note| Google search is used automatically when typing something into the URL bar. A hard-coded keyword trigger is also available using the '''?''' prefix.}}<br />
<br />
==== Tmpfs ====<br />
<br />
===== Cache in tmpfs =====<br />
<br />
{{Note|Chromium stores its cache separate from its browser profile directory.}}<br />
<br />
To limit Chromium from writing its cache to a physical disk, one can define an alternative location via the {{ic|--disk-cache-dir}} flag:<br />
$ chromium --disk-cache-dir="$XDG_RUNTIME_DIR/chromium-cache"<br />
<br />
Cache should be considered temporary and will '''not''' be saved after a reboot or hard lock. Another option is to setup the space in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|2=<br />
tmpfs /home/''username''/.cache tmpfs noatime,nodev,nosuid,size=400M 0 0<br />
}}<br />
<br />
===== Profile in tmpfs =====<br />
<br />
Relocate the browser profile to a [[Wikipedia:Tmpfs|tmpfs]] filesystem, including {{ic|/tmp}}, or {{ic|/dev/shm}} for improvements in application response as the entire profile is now stored in RAM.<br />
<br />
Use an active profile management tool such as {{Pkg|profile-sync-daemon}} for maximal reliability and ease of use. It symlinks or bind mounts and syncs the browser profile directories to RAM. For more, see [[Profile-sync-daemon]].<br />
<br />
==== Launch a new browser instance ====<br />
<br />
When you launch the browser, it first checks if another instance using the same data directory is already running. If there is one, the new window is associated with the old instance. If you want to launch an independent instance of the browser, you must specify separate directory using the {{ic|--user-data-dir}} parameter:<br />
<br />
$ chromium --user-data-dir=''/path/to/some/directory''<br />
<br />
{{Note|The default location of the user data is {{ic|~/.config/chromium/}}.}}<br />
<br />
==== Directly open *.torrent files and magnet links with a torrent client ====<br />
<br />
By default, Chromium downloads {{ic|*.torrent}} files directly and you need to click the notification from the bottom-left corner of the screen in order for the file to be opened with your default torrent client. This can be avoided with the following method:<br />
<br />
* Download a {{ic|*.torrent}} file.<br />
* Right-click the notification displayed at the bottom-left corner of the screen.<br />
* Check the "''Always Open Files of This Type''" checkbox.<br />
<br />
See [[xdg-open]] to change the default assocation.<br />
<br />
==== Touch Scrolling on touchscreen devices ====<br />
<br />
You may need to specify which touch device to use. Find your touchscreen device with {{ic| xinput list}} then launch Chromium with the {{ic|1=--touch-devices='''x'''}} parameter, where "'''x'''" is the id of your device. {{Note|If the device is designated as a slave pointer, using this may not work, use the master pointer's ID instead.}}<br />
<br />
==== Reduce memory usage ====<br />
<br />
By default, Chromium uses a separate OS process for each ''instance'' of a visited web site. [https://www.chromium.org/developers/design-documents/process-models#Supported_Models] However, you can specify command-line switches when starting Chromium to modify this behaviour.<br />
<br />
For example, to share one process for all instances of a website:<br />
<br />
$ chromium --process-per-site<br />
<br />
To use a single process model:<br />
<br />
$ chromium --single-process<br />
<br />
{{Warning|The single-process model is discouraged because it is unsafe and may contain bugs not present in other models.[https://www.chromium.org/developers/design-documents/process-models#TOC-Single-process]}}<br />
<br />
In addition, you can suspend or store inactive Tabs with extensions such as [https://chrome.google.com/webstore/detail/tab-suspender/fiabciakcmgepblmdkmemdbbkilneeeh?hl=en Tab Suspender] and [https://chrome.google.com/webstore/detail/onetab/chphlpgkkbolifaimnlloiipkdnihall?hl=en OneTab].<br />
<br />
==== User Agent ====<br />
<br />
The User Agent can be arbitrarily modified at the start of Chromium's base instance via its {{Ic|<nowiki>--user-agent="[string]"</nowiki>}} parameter.<br />
<br />
==== DOM Distiller ====<br />
<br />
Chromium has a similar reader mode to Firefox. In this case it's called DOM Distiller, which is an [https://github.com/chromium/dom-distiller open source project].<br />
It is disabled by default, but can be enabled using the {{Ic|chrome://flags/#enable-reader-mode}} flag, which you can also make [[#Making flags persistent|persistent]].<br />
Not only does DOM Distiller provide a better reading experience by distilling the content of the page, it also simplifies pages for print. Even though the latter checkbox option has been removed from the print dialog, you can still print the distilled page, which basically has the same effect.<br />
<br />
After enabling the flag, you will find a new "Toggle reader mode" menu item and corresponding icon in the address bar when Chromium thinks the website you are visiting could do with some distilling.<br />
<br />
==== Forcing specific GPU ====<br />
<br />
In multi-GPU systems, Chromium automatically detects which GPU should be used for rendering (discrete or integrated). This works 99% of the time, except when it does not - if a unavailable GPU is picked (for example, discrete graphics on VFIO GPU passthrough-enabled systems), {{ic|chrome://gpu}} will complain about not being able to initialize the GPU process. On the same page below '''Driver Information''' there will be multiple GPUs shown (GPU0, GPU1, ...). There is no way to switch between them in a user-friendly way, but you can read the device/vendor IDs present there and configure Chromium to use a specific GPU with flags:<br />
<br />
$ chromium --gpu-testing-vendor-id=0x8086 --gpu-testing-device-id=0x1912<br />
<br />
...where {{ic|0x8086}} and {{ic|0x1912}} is replaced by the IDs of the GPU you want to use (as shown on the {{ic|chrome://gpu}} page).<br />
<br />
==== Import bookmarks from Firefox ====<br />
<br />
To ease the transition, you can import bookmarks from [[Firefox]] into Chromium.<br />
<br />
Navigate Chromium to {{ic|chrome://settings/importData}}<br />
<br />
If Firefox is already installed on your computer, you can directly import bookmarks as well as many other things from Firefox.<br />
<br />
Make sure '''Mozilla Firefox''' is selected. Optionally, you can uncheck some unwanted items here. Click the '''Import''' and then '''Done'''. You are done with it.<br />
<br />
{{note|If you have not created any bookmarks in Chromium yet, the bookmarks will show up in your bookmarks bar. If you already have bookmarks, the bookmarks will be in a new folder labeled "Imported From Firefox"}}<br />
<br />
If you import bookmarks from another PC, you have to export bookmarks from Firefox first.<br />
<br />
{{ic|''Ctrl + Shift + O > Import and Backup > Export Bookmarks To HTML}} in Firefox''<br />
<br />
The procedure is pretty much the same. You need to go to {{ic|chrome://settings/importData}}. However, this time, in the '''From''' drop-down menu, select '''Bookmarks HTML File''' and click the '''Choose File''' button and upload the desired bookmark file.<br />
<br />
==== Enabling native notifications ====<br />
<br />
Go to {{ic|chrome://flags#enable-system-notifications}} and select ''Enabled''.<br />
<br />
==== U2F authentication ====<br />
<br />
Install {{Pkg|libfido2}} library. This provides the udev rules required to enable access to the [[U2F]] key as a user.<br />
U2F keys are by default only accessible by root, and without these rules Chromium will give an error.<br />
<br />
==== Dark mode ====<br />
<br />
To enable dark mode (used in ''prefers-color-scheme'' in CSS, JavaScript, Settings and Dev-Tools) and enable the dark theme (normally used for incognito mode) [[append]] the following flag to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--force-dark-mode<br />
--enable-features=WebUIDarkMode<br />
}}<br />
<br />
===== Dark mode by system preference =====<br />
<br />
[https://bugs.chromium.org/p/chromium/issues/detail?id=998903 This Chromium issue] aims to bring dark mode based on GTK theme selection into Chromium.<br />
<br />
In the future, all that will be required to properly use system preference, is setting ''Designs'' to GTK in {{ic|chrome://settings/appearance}}.<br />
<br />
=== Profile maintenance ===<br />
<br />
Chromium uses [[SQLite]] databases to manage history and the like. Sqlite databases become fragmented over time and empty spaces appear all around. But, since there are no managing processes checking and optimizing the database, these factors eventually result in a performance hit. A good way to improve startup and some other bookmarks- and history-related tasks is to defragment and trim unused space from these databases.<br />
<br />
{{Pkg|profile-cleaner}} and {{AUR|browser-vacuum}} in the [[AUR]] do just this.<br />
<br />
=== Security ===<br />
<br />
==== WebRTC ====<br />
<br />
WebRTC is a communication protocol that relies on JavaScript that can leak one's actual IP address and hardware hash from behind a VPN. While some software may prevent the leaking scripts from running, it's probably a good idea to block this protocol directly as well, just to be safe. As of October 2016, there is no way to disable WebRTC on Chromium on desktop, there are extensions available to disable local IP address leak, one is this [https://chrome.google.com/webstore/detail/webrtc-network-limiter/npeicpdbkakmehahjeeohfdhnlpdklia extension].<br />
<br />
One can test WebRTC via [https://www.privacytools.io/webrtc.html this page].<br />
<br />
{{Warning|Even though IP leak can be prevented, Chromium still sends your unique hash, and there is no way to prevent this. Read more on https://www.browserleaks.com/webrtc#webrtc-disable }}<br />
<br />
==== SSL certificates ====<br />
<br />
Chromium does not have an SSL certificate manager. It relies on the NSS Shared DB {{ic|~/.pki/nssdb}}. In order to add SSL certificates to the database, users will have to use the shell.<br />
<br />
===== Adding CAcert certificates for self-signed certificates =====<br />
<br />
Grab the CAcerts and create an {{ic|nssdb}}, if one does not already exist. To do this, first install the {{Pkg|nss}} package, then complete these steps:<br />
<br />
$ mkdir -p $HOME/.pki/nssdb<br />
$ cd $HOME/.pki/nssdb<br />
$ certutil -N -d sql:.<br />
<br />
$ curl -k -o "cacert-root.crt" "http://www.cacert.org/certs/root.crt"<br />
$ curl -k -o "cacert-class3.crt" "http://www.cacert.org/certs/class3.crt"<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org" -i cacert-root.crt <br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org Class 3" -i cacert-class3.crt<br />
<br />
{{Note|Users will need to create a password for the database, if it does not exist.}}<br />
<br />
Now users may manually import a self-signed certificate.<br />
<br />
===== Example 1: Using a shell script to isolate the certificate from TomatoUSB =====<br />
<br />
Below is a simple script that will extract and add a certificate to the user's {{ic|nssdb}}:<br />
<br />
#!/bin/sh<br />
#<br />
# usage: import-cert.sh remote.host.name [port]<br />
#<br />
REMHOST=$1<br />
REMPORT=${2:-443}<br />
exec 6>&1<br />
exec > $REMHOST<br />
echo | openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'<br />
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "$REMHOST" -i $REMHOST <br />
exec 1>&6 6>&-<br />
<br />
Syntax is advertised in the commented lines.<br />
<br />
References:<br />
*https://web.archive.org/web/20180718193807/https://blog.avirtualhome.com/adding-ssl-certificates-to-google-chrome-linux-ubuntu<br />
*https://chromium.googlesource.com/chromium/src/+/master/docs/linux/cert_management.md<br />
<br />
===== Example 2: Using Firefox to isolate the certificate from TomatoUSB =====<br />
<br />
The {{Pkg|firefox}} browser can be used to save the certificate to a file for manual import into the database.<br />
<br />
Using firefox:<br />
#Browse to the target URL.<br />
#Upon seeing the "This Connection is Untrusted" warning screen, click: ''I understand the Risks > Add Exception...''<br />
#Click: ''View > Details > Export'' and save the certificate to a temporary location ({{ic|/tmp/easy.pem}} in this example).<br />
<br />
Now import the certificate for use in Chromium:<br />
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "easy" -i /tmp/easy.pem<br />
<br />
{{Note|Adjust the name to match that of the certificate. In the example above, "easy" is the name of the certificate.}}<br />
<br />
Reference:<br />
*https://sahissam.blogspot.com/2012/06/new-ssl-certificates-for-tomatousb-and.html<br />
<br />
==== Canvas Fingerprinting ====<br />
<br />
Canvas fingerprinting is a technique that allows websites to identify users by detecting differences when rendering to an HTML5 canvas. This information can be made inaccessible by using the {{ic|--disable-reading-from-canvas}} flag.<br />
<br />
To confirm this is working run [https://panopticlick.eff.org this test] and make sure "hash of canvas fingerprint" is reported as undetermined in the full results.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Some extensions require reading from canvas and may be broken by setting {{ic|--disable-reading-from-canvas}}.<br />
* YouTube player does not work properly without canvas reading. [https://github.com/qutebrowser/qutebrowser/issues/5345][https://bbs.archlinux.org/viewtopic.php?pid=1907406]<br />
}}<br />
<br />
==== Privacy extensions ====<br />
<br />
See [[Browser extensions#Privacy]].<br />
<br />
{{Tip|Installing too many extensions might take up much space in the toolbar. Those extensions which you would not interact with anyway (e.g. [https://chrome.google.com/webstore/detail/gcbommkclmclpchllfjekcdonpmejbdp HTTPS Everywhere]) can be hidden by right-clicking on the extension and choosing ''Hide in Chromium menu''.}}<br />
<br />
==== Do Not Track ====<br />
<br />
To enable [[wikipedia:Do Not Track|Do Not Track]], visit {{ic|chrome://settings}}, scroll down to ''Advanced'' and under ''Privacy and security'', check ''Send a "Do Not Track" request with your browsing traffic''.<br />
<br />
==== Force a password store ====<br />
<br />
Chromium uses a password store to store your passwords and the ''Chromium Safe Storage'' key, which is used to encrypt cookie values. [https://codereview.chromium.org/24734007]<br />
<br />
By default Chromium auto-detects which password store to use, which can lead to you apparently losing your passwords and cookies when switching to another desktop environment or window manager.<br />
<br />
You can force Chromium to use a specific password store by launching it with the {{ic|--password-store}} flag with one of following the values [https://chromium.googlesource.com/chromium/src/+/master/docs/linux/password_storage.md]:<br />
<br />
* {{ic|gnome}}, uses [[Gnome Keyring]]<br />
* {{ic|kwallet5}}, uses [[KDE Wallet]]<br />
* {{ic|basic}}, saves the passwords and the cookies' encryption key as plain text in the file {{ic|Login Data}}<br />
* {{ic|detect}}, the default auto-detect behavior<br />
<br />
For example, to force Chromium to use Gnome Keyring in another desktop or WM use {{ic|1=--password-store=gnome}}, see [[#Making flags persistent]] for making it permanent.<br />
<br />
When using a password store of another desktop environment you probably also want to unlock it automatically see: [[GNOME/Keyring#Using the keyring outside of GNOME]] and [[KDE Wallet#Unlock KDE Wallet automatically on login]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Fonts ===<br />
<br />
{{Note|Chromium does not fully integrate with fontconfig/GTK/Pango/X/etc. due to its sandbox. For more information, see the [https://dev.chromium.org/developers/linux-technical-faq Linux Technical FAQ].}}<br />
<br />
==== Tab font size is too large ====<br />
<br />
Chromium will use the GTK settings as described in [[GTK#Configuration]]. When configured, Chromium will use the {{ic|gtk-font-name}} setting for tabs (which may mismatch window font size). To override these settings, use {{ic|1=--force-device-scale-factor=1.0}}.<br />
<br />
=== WebGL ===<br />
<br />
There is the possibility that your graphics card has been blacklisted by Chromium. See [[#Force GPU acceleration]].<br />
<br />
If you are using Chromium with [[Bumblebee]], WebGL might crash due to GPU sandboxing. In this case, you can disable GPU sandboxing with {{ic|optirun chromium --disable-gpu-sandbox}}.<br />
<br />
Visit {{ic|chrome://gpu/}} for debugging information about WebGL support.<br />
<br />
Chromium can save incorrect data about your GPU in your user profile (e.g. if you use switch between an Nvidia card using Optimus and Intel, it will show the Nvidia card in {{ic|chrome://gpu}} even when you are not using it or primusrun/optirun). Running using a different user directory, e.g, {{ic|1=chromium --user-data-dir=$(mktemp -d)}} may solve this issue. For a persistent solution you can reset the GPU information by deleting {{ic|~/.config/chromium/Local\ State}}.<br />
<br />
=== Incorrect HiDPI rendering ===<br />
<br />
Chromium will automatically scale for a [[HiDPI]] display, however, this may cause an incorrect rendered GUI.<br />
<br />
The flag {{ic|1=--force-device-scale-factor=1}} may be used to overrule the automatic scaling factor.<br />
<br />
When [[#Native Wayland support|native Wayland support]] is enabled, Chromium will automatically scale based on the configured scale of each monitor.<br />
<br />
=== Password prompt on every start with GNOME Keyring ===<br />
<br />
See [[GNOME/Keyring#Passwords are not remembered]].<br />
<br />
=== Chromecasts in the network are not discovered ===<br />
<br />
You will need to enable the Media Router Component Extension in {{ic|chrome://flags/#load-media-router-component-extension}}.<br />
<br />
=== Everything is syncing except for password ===<br />
<br />
If synchronization is not working for password only (you can check it on {{ic|chrome://sync-internals/}}) delete profile login data:<br />
<br />
$ rm ~/.config/chromium/Default/Login\ Data*<br />
<br />
See [https://support.google.com/chrome/thread/9947763?hl=en&msgid=23687608 Google Chrome Help forum] for details.<br />
<br />
=== Losing cookies and passwords when switching between desktop environments ===<br />
<br />
If you see the message {{ic|Failed to decrypt token for service AccountId-*}} in the terminal when you start Chromium, it might try to use the wrong password storage backend. This might happen when you switch between Desktop Environments.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Hang on startup when Google Sync enabled ===<br />
<br />
Try launching Chrome with {{ic|1=--password-store=basic}} or another appropriate password store.<br />
<br />
See [[#Force a password store]].<br />
<br />
=== Chromium asks to be set as the default browser every time it starts ===<br />
<br />
If you are using KDE and have once set Firefox as the default browser (by clicking the button inside Firefox), you might find Chromium asks to be set as the default browser every time it starts, even if you click the "set as default" button.<br />
<br />
Chromium checks for this status by running {{ic|xdg-settings check default-web-browser chromium.desktop}}. If the output is "no", it is not considering itself to be the default browser. The script {{ic|xdg-settings}} checks for the following MIME associations and expect all of them to be {{ic|chromium.desktop}}:<br />
<br />
{{bc|<br />
x-scheme-handler/http<br />
x-scheme-handler/https<br />
text/html}}<br />
<br />
To fix it, go to ''System settings > Applications > Default applications > Web browser'' and choose Chromium. Then, set the MIME association for {{ic|text/html}}:<br />
<br />
$ xdg-mime default chromium.desktop text/html<br />
<br />
Finally, [[XDG_MIME_Applications#New_MIME_types|update the MIME database]]:<br />
<br />
$ update-mime-database ~/.local/share/mime<br />
<br />
=== "This browser or app may not be secure" error logging in to Google ===<br />
<br />
As of 2020.04.20 if you run chromium with {{ic|1=--remote-debugging-port=9222}} flag for web development, you cannot log in to your Google account. Temporarily disable this flag to login and then you can enable it back.<br />
<br />
=== Chromium stuck at 60fps when using a 144Hz + 60Hz monitor ===<br />
<br />
There is a suitable workaround for this issue, [[append]] the following flags to [[#Making flags persistent|persistent configuration]]:<br />
<br />
{{hc|1=~/.config/chromium-flags.conf|2=<br />
--use-gl=egl<br />
--ignore-gpu-blocklist<br />
--enable-gpu-rasterization<br />
}}<br />
<br />
This should make Chromium run at 144fps when used on your 144hz display, assuming your compositor is refreshing at 144fps. <br />
Keep in mind it might be a little choppy {{Bug|67035}}, but this is way better than it being stuck at 60fps.<br />
<br />
=== Chromium low scroll speed ===<br />
<br />
Mouse whell scrolling in chromium and electron based applications may be too slow for daily usage. Here are some solutions.<br />
<br />
[[Libinput#Mouse wheel scrolling speed scaling]] injects {{ic|libinput_event_pointer_get_axis_value}} function in libinput and provides an interface to change scale factor. This is not a application level injection, so an addition script for application specific scale factor tuning is needed. Note that scroll on chromium's small height developer tools may be too fast when scale factor is large enough.<br />
<br />
[[IMWheel]] increases scroll distance by replaying X wheel button event for multiple times. However, chromium assumes the real scroll and the replayed ones as two events. There is a small but noticeable delay tween them, so one mouse wheel scroll leads to twice page jumps. Also, touchpad scroll needs addition care.<br />
<br />
[https://chrome.google.com/webstore/detail/linux-scroll-speed-fix/mlboohjioameadaedfjcpemcaangkkbp Linux Scroll Speed Fix] and [https://chrome.google.com/webstore/detail/smoothscroll/nbokbjkabcmbfdlbddjidfmibcpneigj SmoothScroll] are two chromium extensions with suppport for scroll distance modification. Upon wheel scroll in a web page, the closest scrollable ancestor of current focused node will be found, then a scroll method with given pixel distance will be called on it, even if it has been scrolled to bottom. So once you scroll into a text editor or any scrollable element, you can never scroll out of it, except moving mouse. Also, extension based methods can not be used outside chromium.<br />
<br />
== See also ==<br />
<br />
* [https://www.chromium.org/ Chromium homepage]<br />
* [https://chromereleases.googleblog.com/ Google Chrome release notes]<br />
* [https://chrome.google.com/webstore/ Chrome web store]<br />
* [[Wikipedia:Chromium (web browser)#Differences from Google Chrome|Differences between Chromium and Google Chrome]]<br />
* [https://peter.sh/experiments/chromium-command-line-switches/ List of Chromium command-line switches]<br />
* [[Profile-sync-daemon]] - Systemd service that saves Chromium profile in tmpfs and syncs to disk<br />
* [[Tmpfs]] - Tmpfs Filesystem in {{ic|/etc/fstab}}<br />
* [https://www.kernel.org/doc/html/latest/filesystems/tmpfs.html Official tmpfs kernel Documentation]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Fonts&diff=685416Fonts2021-07-05T01:22:27Z<p>Thiagowfx: /* Monospaced */ add hermit</p>
<hr />
<div>[[Category:Fonts]]<br />
[[de:Schriftarten]]<br />
[[es:Fonts]]<br />
[[it:Fonts]]<br />
[[ja:フォント]]<br />
[[zh-hans:Fonts]]<br />
[[zh-hant:Fonts]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related|Linux console#Fonts}}<br />
{{Related|Java Runtime Environment fonts}}<br />
{{Related|Metric-compatible fonts}}<br />
{{Related|Microsoft fonts}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Computer font]]: "A computer font (or font) is an electronic data file containing a set of glyphs, characters, or symbols such as dingbats."<br />
<br />
Note that certain font licenses may impose some legal limitations.<br />
<br />
== Font formats ==<br />
<br />
Most computer fonts used today are in either ''bitmap'' or ''outline'' data formats. <br />
;Bitmap fonts: Consist of a matrix of dots or pixels representing the image of each glyph in each face and size.<br />
;Outline or ''vector'' fonts: Use Bézier curves, drawing instructions and mathematical formulae to describe each glyph, which make the character outlines scalable to any size.<br />
<br />
=== Bitmap formats ===<br />
<br />
* [[Wikipedia:Glyph Bitmap Distribution Format|Bitmap Distribution Format]] (BDF) by Adobe<br />
* [[Wikipedia:Portable Compiled Format|Portable Compiled Format]] (PCF) by Xorg<br />
* [[Wikipedia:PC Screen Font|PC Screen Font]] (PSF) used by the Kernel for console fonts, not supported by Xorg (for Unicode PSF files the extension is {{ic|psfu}})<br />
<br />
These formats can also be gzipped. See [[#Bitmap]] for the available bitmap fonts.<br />
<br />
=== Outline formats ===<br />
<br />
* [[Wikipedia:PostScript fonts|PostScript fonts]] by Adobe – has various formats, e.g: Printer Font ASCII (PFA) and Printer Font Binary (PFB)<br />
* [[Wikipedia:TrueType|TrueType]] by Apple and Microsoft (file extension: {{ic|ttf}})<br />
* [[Wikipedia:OpenType|OpenType]] by Microsoft, built on TrueType (file extensions: {{ic|otf}}, {{ic|ttf}})<br />
<br />
For most purposes, the technical differences between TrueType and OpenType can be ignored.<br />
<br />
=== Other formats ===<br />
<br />
The typesetting application [[TeX]] and its companion font software, ''Metafont,'' traditionally renders characters using its own methods. Some file extensions used for fonts from these two programs are {{ic|*pk}}, {{ic|*gf}}, {{ic|mf}} and {{ic|vf}}. Modern versions can also use TrueType and OpenType fonts.<br />
<br />
[https://fontforge.github.io/en-US/ FontForge] ({{Pkg|fontforge}}), a font editing application, can store fonts in its native text-based format, {{ic|sfd}}, ''s''pline ''f''ont ''d''atabase.<br />
<br />
The [https://www.w3.org/TR/SVG/fonts.html SVG] format also has its own font description method.<br />
<br />
== Installation ==<br />
<br />
There are various methods for installing fonts.<br />
<br />
=== Pacman ===<br />
<br />
Fonts and font collections in the enabled repositories can be installed using [[pacman]].<br />
<br />
Available fonts may be found by [[pacman#Querying package databases|querying packages]] (e.g. for {{ic|font}} or {{ic|ttf}}).<br />
<br />
=== Creating a package ===<br />
<br />
You should give pacman the ability to manage your fonts, which is done by [[Creating packages|creating an Arch package]]. These can also be shared with the community in the [[AUR]]. The packages to install fonts are particularly similar; see [[Font packaging guidelines]].<br />
<br />
The family name of a font file can be aquired with the use of {{ic|fc-query}} for example: {{ic|fc-query -f '%{family[0]}\n' /path/to/file}}. The formatting is described in {{man|3|FcPatternFormat}}.<br />
<br />
=== Manual installation ===<br />
<br />
The recommended way of adding fonts that are not in the repositories to your system is described in [[#Creating a package]]. This gives pacman the ability to remove or update them at a later time.<br />
<br />
Alternatively, fonts can be installed manually:<br />
<br />
* For a single user, install fonts to {{ic|~/.local/share/fonts/}}.<br />
** In many cases this suffices, unless you run graphical applications as other users.<br />
** In the past {{ic|~/.fonts/}} was used, but is now deprecated.<br />
* For system-wide (all users) installation, place your fonts under {{ic|/usr/local/share/fonts/}}.<br />
** You may need to create the directory first; {{ic|mkdir -p /usr/local/share/fonts}}.<br />
** {{ic|/usr/share/fonts/}} is under the purview of the package manager, and shouldn't be modified manually.<br />
<br />
The creation of a subdirectory structure is up to the user, and varies among Linux distributions. For clarity, it's good to keep each font in its own directory. Fontconfig will search its default paths recursively, ensuring nested files get picked up.<br />
<br />
An example structure might be:<br />
<br />
/usr/local/share/fonts/<br />
├── otf<br />
│ └── SourceCodeVariable<br />
│ ├── SourceCodeVariable-Italic.otf<br />
│ └── SourceCodeVariable-Roman.otf<br />
└── ttf<br />
├── AnonymousPro<br />
│ ├── Anonymous-Pro-B.ttf<br />
│ ├── Anonymous-Pro-I.ttf<br />
│ └── Anonymous-Pro.ttf<br />
└── CascadiaCode<br />
├── CascadiaCode-Bold.ttf<br />
├── CascadiaCode-Light.ttf<br />
└── CascadiaCode-Regular.ttf<br />
<br />
The font files need to have sufficient read permissions for all users, i.e. at least [[chmod]] {{ic|444}} for files, and {{ic|555}} for directories.<br />
<br />
For the Xserver to load fonts directly (as opposed to the use of a ''font server''), the directory for your newly added font must be added with a FontPath entry. This entry is located in the ''Files'' section of your [[Xorg#Configuration|Xorg configuration file]] (e.g. {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/xorg.conf}}). See [[#Older applications]] for more detail.<br />
<br />
Finally, update the fontconfig cache (usually unnecessary as software using the fontconfig library does this):<br />
<br />
$ fc-cache<br />
<br />
=== Older applications ===<br />
<br />
With older applications that do not support fontconfig (e.g. GTK 1.x applications, and {{ic|xfontsel}}) the index will need to be created in the font directory:<br />
<br />
$ mkfontscale<br />
$ mkfontdir<br />
<br />
Or to include more than one folder with one command:<br />
<br />
$ for dir in /font/dir1/ /font/dir2/; do xset +fp $dir; done && xset fp rehash<br />
<br />
Or if fonts were installed in a different sub-folders under the e.g. {{ic|/usr/share/fonts}}:<br />
<br />
$ for dir in * ; do if [ -d "$dir" ]; then cd "$dir";xset +fp "$PWD" ;mkfontscale; mkfontdir;cd .. ;fi; done && xset fp rehash<br />
<br />
At times the X server may fail to load the fonts directory and you will need to rescan all the {{ic|fonts.dir}} files:<br />
<br />
# xset +fp /usr/share/fonts/misc # Inform the X server of new directories<br />
# xset fp rehash # Forces a new rescan<br />
<br />
To check that the font(s) is included:<br />
<br />
$ xlsfonts | grep fontname<br />
<br />
{{Note|Many packages will automatically configure Xorg to use the font upon installation. If that is the case with your font, this step is not necessary.}}<br />
<br />
This can also be set globally in {{ic|/etc/X11/xorg.conf}} or {{ic|/etc/X11/xorg.conf.d}}.<br />
<br />
Here is an example of the section that must be added to {{ic|/etc/X11/xorg.conf}}. Add or remove paths based on your particular font requirements.<br />
<br />
# Let X.Org know about the custom font directories<br />
Section "Files"<br />
FontPath "/usr/share/fonts/100dpi"<br />
FontPath "/usr/share/fonts/75dpi"<br />
FontPath "/usr/share/fonts/cantarell"<br />
FontPath "/usr/share/fonts/cyrillic"<br />
FontPath "/usr/share/fonts/encodings"<br />
FontPath "/usr/share/fonts/misc"<br />
FontPath "/usr/share/fonts/truetype"<br />
FontPath "/usr/share/fonts/TTF"<br />
FontPath "/usr/share/fonts/util"<br />
EndSection<br />
<br />
=== Pango Warnings ===<br />
<br />
When [https://www.pango.org/ Pango] is in use on your system it will read from [https://www.freedesktop.org/wiki/Software/fontconfig fontconfig] to sort out where to source fonts.<br />
<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='common'<br />
(process:5741): Pango-WARNING **: failed to choose a font, expect ugly output. engine-type='PangoRenderFc', script='latin'<br />
<br />
If you are seeing errors similar to this and/or seeing blocks instead of characters in your application then you need to add fonts and update the font cache. This example uses the {{Pkg|ttf-liberation}} fonts to illustrate the solution (after successful installation of the package) and runs as root to enable them system-wide.<br />
<br />
{{hc|# fc-cache|<br />
/usr/share/fonts: caching, new cache contents: 0 fonts, 3 dirs<br />
/usr/share/fonts/TTF: caching, new cache contents: 16 fonts, 0 dirs<br />
/usr/share/fonts/encodings: caching, new cache contents: 0 fonts, 1 dirs<br />
/usr/share/fonts/encodings/large: caching, new cache contents: 0 fonts, 0 dirs<br />
/usr/share/fonts/util: caching, new cache contents: 0 fonts, 0 dirs<br />
/var/cache/fontconfig: cleaning cache directory<br />
fc-cache: succeeded<br />
}}<br />
<br />
You can test for a default font being set like so:<br />
<br />
{{hc|$ fc-match|<br />
LiberationMono-Regular.ttf: "Liberation Mono" "Regular"<br />
}}<br />
<br />
== Font packages ==<br />
<br />
This is a selective list that includes many font packages from the [[AUR]] along with those in the official repositories. Fonts are tagged "Unicode" if they have wide [[wikipedia:unicode|Unicode]] support.<br />
<br />
{{Tip|[https://github.com/ternstor/distrofonts Archfonts] is a Python script that can be used to generate an overview of all the TTF fonts found in the official repositories and in the AUR.}}<br />
<br />
=== Bitmap ===<br />
<br />
{{Note|{{Pkg|pango}} 1.44 [https://blogs.gnome.org/mclasen/2019/05/25/pango-future-directions/ dropped support for FreeType in favor of HarfBuzz] thus [https://blogs.gnome.org/mclasen/2019/08/07/pango-1-44-wrap-up/ losing support for traditional BDF/PCF bitmap fonts], so applications like e.g. {{Pkg|gnome-terminal}} will not work with such fonts anymore, showing rectangles instead of glyphs. See {{Bug|63297}}, [https://gitlab.gnome.org/GNOME/pango/issues/386 Pango issue #386] and [https://github.com/harfbuzz/harfbuzz/issues/1897 HarfBuzz issue #1897].}}<br />
<br />
* Default 8x16<br />
* [https://github.com/seraxis/pcf-spectrum-berry Berry] ({{AUR|pcf-spectrum-berry}}) - 8px<br />
* [https://www.dcmembers.com/jibsen/download/61/ Dina] ({{Pkg|dina-font}}) – 6pt, 8pt, 9pt, 10pt, monospaced, based on Proggy<br />
* [http://openlab.jp/efont/unicode/ Efont] ({{AUR|efont-unicode-bdf}}) – 10px, 12px, 14px, 16px, 24px, normal, bold and italic<br />
* [https://font.gohu.org/ Gohu] ({{AUR|gohufont}}) – 11px, 14px, normal and bold<br />
* [http://artwizaleczapka.sourceforge.net/ Lime] ({{AUR|artwiz-fonts}})<br />
* [https://tobiasjung.name/profont/ ProFont] ({{AUR|ttf-profont-iix}}) – 10px, 11px, 12px, 15px, 17px, 22px, 29px, normal<br />
* [[Wikipedia:Proggy programming fonts|Proggy]] ({{AUR|proggyfonts}}) – has different variants<br />
* [http://www.fial.com/~scott/tamsyn-font/ Tamsyn] ({{Pkg|tamsyn-font}})<br />
* [http://terminus-font.sourceforge.net/ Terminus] ({{Pkg|terminus-font}})<br />
* [https://github.com/lucy/tewi-font Tewi] ({{AUR|bdf-tewi-git}})<br />
* [https://unifoundry.com/unifont.html Unifont] ([[Wikipedia:Unicode font#Comparison of fonts|most extensive]] Unicode coverage of any font) ({{Pkg|bdf-unifont}})<br />
<br />
Works with pango 1.44:<br />
* [https://tobiasjung.name/profont/ ProFont] ({{AUR|profont-otb}}) - OpenType Bitmap (OTB) variant of ProFont<br />
* [https://xorg.freedesktop.org/releases/individual/font/ Misc Fixed] {{AUR|xorg-fonts-misc-otb}}<br />
* [https://font.gohu.org/ Gohufont] ({{AUR|gohufont-otb}})<br />
* [https://github.com/slavfox/Cozette/ Cozette] ({{AUR|cozette-otb}})<br />
* More [https://aur.archlinux.org/packages/?O=0&SeB=n&K=-otb&outdated=&SB=n&SO=a&PP=50&do_Search=Go otb] fonts on AUR<br />
<br />
=== Latin script ===<br />
<br />
==== Families ====<br />
<br />
Packages [[Font package guidelines#Provides|providing a base font set]]:<br />
* [[Wikipedia:Bitstream Vera|Bitstream Vera]] ({{Pkg|ttf-bitstream-vera}}) – serif, sans-serif, and monospace<br />
* [[Wikipedia:Croscore fonts|Croscore fonts]] ({{Pkg|ttf-croscore}}) – Chrome OS' substitute for Windows' Arial, Times New Roman, and Courier New using the same metric<br />
* [[Wikipedia:DejaVu fonts|DejaVu fonts]] ({{Pkg|ttf-dejavu}}) – Bitstream Vera modified for greater Unicode coverage<br />
* [[Wikipedia:Droid (font)|Droid]] ({{Pkg|ttf-droid}}) – default font for older Android versions with wide Unicode coverage including CJK but not symbols and emojis<br />
* [[Wikipedia:GNU FreeFont|GNU FreeFont]] ({{Pkg|gnu-free-fonts}}) – free sans, sans serif and monospace fonts in the OpenType scalable format, good Unicode coverage however does not include CJK<br />
* [[Wikipedia:IBM Plex|IBM Plex]] ({{Pkg|ttf-ibm-plex}}) – serif, sans-serif, condensed sans-serif and monospace with true italics<br />
* [[Wikipedia:Liberation fonts|Liberation fonts]] ({{Pkg|ttf-liberation}}) – free metric-compatible substitute for the Arial, Arial Narrow, Times New Roman and Courier New fonts found in Windows and Microsoft Office products<br />
* [[Wikipedia:Linux Libertine|Linux Libertine]] ({{Pkg|ttf-linux-libertine}}) – serif (Libertine) and sans serif (Biolinum) fonts with large Unicode coverage<br />
* [[Microsoft fonts]] ({{AUR|ttf-ms-win10}}) – Windows 10 fonts (Windows 10 installation or installation medium needed)<br />
* [[Wikipedia:Noto fonts|Noto fonts]] ({{Pkg|noto-fonts}}) – Google font family with full Unicode coverage if installed with its emoji and CJK optional dependencies<br />
<br />
Packages not providing a base font set:<br />
* [https://b612-font.com/ B612] ({{AUR|ttf-b612}}) – open source font family (sans and mono) sponsored by Airbus, designed for comfort of reading on aircraft cockpit screens<br />
* [[Wikipedia:Luxi fonts|Luxi fonts]] ({{AUR|font-bh-ttf}}) – X.Org font family similar to Lucida<br />
* [[Wikipedia:Roboto|Roboto]] ({{Pkg|ttf-roboto}}) – default font for newer Android versions where it is complemented by Noto fonts for languages not supported like CJK<br />
* [http://www.gust.org.pl/projects/e-foundry/tex-gyre/index_html TeX Gyre fonts] ({{pkg|tex-gyre-fonts}}) – free substitute for Helvetica, Times New Roman, Palatino, Bookman and other popular fonts by the Polish GUST association of TeX users <br />
* [[Wikipedia:Ubuntu Font Family|Ubuntu font family]] ({{Pkg|ttf-ubuntu-font-family}})<br />
<br />
Legacy Microsoft font packages:<br />
* [http://corefonts.sourceforge.net/ Microsoft fonts] ({{AUR|ttf-ms-fonts}}) – Andalé Mono, Courier New, Arial, Arial Black, Comic Sans, Impact, Lucida Sans, Microsoft Sans Serif, Trebuchet, Verdana, Georgia, Times New Roman<br />
* Vista fonts ({{AUR|ttf-vista-fonts}}) – Consolas, Calibri, Candara, Corbel, Cambria, Constantia<br />
<br />
==== Monospaced ====<br />
<br />
Fonts supporting [[Wikipedia:Orthographic_ligature#Programming_languages|programming ligatures]] are identified below with a ⟶ sign. For more monospaced fonts, also see [[#Bitmap]] and [[#Families]].<br />
<br />
* [https://www.marksimonson.com/fonts/view/anonymous-pro Anonymous Pro] ({{Pkg|ttf-anonymous-pro}}, included in {{AUR|ttf-google-fonts-git}})<br />
* [https://github.com/microsoft/cascadia-code Cascadia Code] ({{Pkg|ttf-cascadia-code}}) ⟶ – designed to enhance the look of the Windows Terminal, with programming ligatures, released by Microsoft under the Open Font License.<br />
* [https://quoteunquoteapps.com/courierprime/ Courier Prime] ({{AUR|ttf-courier-prime}}) – Courier alternative which has been supplemented by a sans serif font and a version optimized for programming, released under the Open Font License.<br />
* [https://damieng.com/envy-code-r Envy Code R] ({{AUR|ttf-envy-code-r}}) – font designed for programmers<br />
* Fantasque Sans Mono ({{Pkg|ttf-fantasque-sans-mono}}, {{Pkg|otf-fantasque-sans-mono}})<br />
* [[Wikipedia:Fira_(typeface)|Fira Mono]] ({{Pkg|ttf-fira-mono}}, {{Pkg|otf-fira-mono}}) – font optimized for small screens and adopted by Mozilla for the Firefox OS<br />
* [[Wikipedia:Fira_(typeface)#Fira_Code|Fira Code]] ({{Pkg|ttf-fira-code}}) ⟶ – extension of Fira Mono with programming ligatures for common programming multi-character combinations<br />
* [https://sourcefoundry.org/hack/ Hack] ({{Pkg|ttf-hack}}) - an open source monospaced font, used as the default in KDE Plasma<br />
* [https://pcaro.es/p/hermit/ Hermit] ({{Pkg|otf-hermit}}) - a font for programmers, by a programmer<br />
* [[Wikipedia:Inconsolata|Inconsolata]] ({{Pkg|ttf-inconsolata}}, included in {{AUR|ttf-google-fonts-git}}) – designed for source code listing, inspired by Consolas and Letter Gothic<br />
* [https://leonardo-m.livejournal.com/77079.html Inconsolata-g] ({{AUR|ttf-inconsolata-g}}) – adds some programmer-friendly modifications<br />
* [https://be5invis.github.io/Iosevka/ Iosevka] ({{AUR|ttf-iosevka}}) ⟶ – slender sans-serif and slab-serif typeface inspired by Pragmata Pro, M+ and PF DIN Mono, designed to be the ideal font for programming; it supports programming ligatures and over 2000 latin, greek, cyrillic, phonetic and PowerLine glyphs<br />
* [https://www.jetbrains.com/lp/mono/ JetBrains Mono] ({{Pkg|ttf-jetbrains-mono}}) ⟶ – the free and open-source typeface for developers<br />
* [[Wikipedia:Lucida Typewriter|Lucida Typewriter]] (included in package {{AUR|jre}})<br />
* [[Wikipedia:Menlo (typeface)|Menlo]] ({{AUR|ttf-meslo}}) – customized version of Apple's Menlo Regular font for OS X with larger vertical gap spacing<br />
* [[Wikipedia:Monaco (typeface)|Monaco]] ({{AUR|ttf-monaco}}) – proprietary font designed by Apple for OS X<br />
* Monofur ({{Pkg|ttf-monofur}})<br />
* [https://madmalik.github.io/mononoki Mononoki] ({{AUR|ttf-mononoki}}) – a font for programming and code review<br />
* [[Wikipedia:Source Code Pro|Source Code Pro]] ({{Pkg|adobe-source-code-pro-fonts}}, included in {{AUR|ttf-google-fonts-git}})<br />
<br />
Relevant websites:<br />
<br />
* [http://www.lowing.org/fonts/ Trevor Lowing's font list]<br />
* [https://www.slant.co/topics/67/~what-are-the-best-programming-fonts Slant: What are the best programming fonts?]<br />
* [https://stackoverflow.com/questions/4689/recommended-fonts-for-programming Stack Overflow: Recommended fonts for programming]<br />
* [https://www.programmingfonts.org Programming Fonts - Test Drive]<br />
* [http://s9w.io/font_compare Programming Fonts Compare]<br />
<br />
==== Sans-serif ====<br />
<br />
* [http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=andika Andika] ({{AUR|ttf-andika}})<br />
* [[Wikipedia:Cantarell (typeface)|Cantarell]] ({{Pkg|cantarell-fonts}}) – default font supplied with GNOME, it is required by the GNOME and GTK 3 related packages<br />
* [https://typedesigndead.coosucks.repl.co/ DMCA Sans Serif] ({{AUR|ttf-dmcasansserif}}) – General purpose sans serif font metric-compatible with Microsoft Consolas<br />
* [[Wikipedia:GNU FreeFont|FreeSans]] ({{Pkg|gnu-free-fonts}}) – Unicode<br />
* [https://github.com/rsms/inter Inter UI] ({{Pkg|inter-font}}) – designed for user interfaces<br />
* [https://indestructibletype.com/Jost.html Jost*] ({{AUR|otf-jost}}) - An open-source typeface based on [[Wikipedia:Futura (typeface)|Futura]]<br />
* [[Wikipedia:Open Sans|Open Sans]] ({{Pkg|ttf-opensans}}) – sans serif font commissioned by Google, based on Droid sans but slightly wider.<br />
* [[Wikipedia:PT Sans|PT Sans]] ({{AUR|ttf-google-fonts-git}}) – 3 major variations: normal, narrow, and caption - Unicode: Latin, Cyrillic<br />
* [[Wikipedia:Source Sans|Source Sans]] ({{Pkg|adobe-source-sans-fonts}}) – open source sans serif font from Adobe with a design based on News Gothic and Franklin Gothic<br />
* [[Wikipedia:Tahoma (typeface)|Tahoma]] ({{AUR|ttf-tahoma}})<br />
<br />
==== Serif ====<br />
<br />
* [https://indestructibletype.com/Bodoni.html Bodoni*] ({{AUR|otf-bodoni}}) - An open-source [[Wikipedia:Bodoni|Bodoni]] revival<br />
* [https://github.com/octaviopardo/EBGaramond12 EB Garamond] ({{AUR|ebgaramond-otf}}) - An open-source [[Wikipedia:Garamond|Garamond]] revival<br />
* [[Wikipedia:GNU FreeFont|FreeSerif]] ({{Pkg|gnu-free-fonts}}) - Unicode<br />
* [[Wikipedia:Gentium|Gentium]] ({{Pkg|gentium-plus-font}}) - Unicode: Latin, Greek, Cyrillic, Phonetic Alphabet<br />
* [[Wikipedia:Linux Libertine|Linux Libertine]] ({{Pkg|ttf-linux-libertine}}) - Unicode: Latin, Greek, Cyrillic, Hebrew<br />
<br />
==== Unsorted ====<br />
<br />
{{Style|This section should be absorbed into the Monospace/Serif/Sans-Serif structure}}<br />
<br />
* {{AUR|ttf-cheapskate}} - Font collection from ''dustismo.com''<br />
* {{Pkg|ttf-junicode}} - Junius font containing almost complete medieval latin script glyphs<br />
* {{AUR|ttf-mph-2b-damase}} - Covers full plane 1 and several scripts<br />
* {{Pkg|xorg-fonts-type1}} - IBM Courier and Adobe Utopia sets of [[Wikipedia:PostScript fonts|PostScript fonts]]<br />
* {{AUR|all-repository-fonts}} - Meta package for all fonts in the official repositories.<br />
* {{AUR|ttf-google-fonts-git}} - a huge collection of free fonts (including Ubuntu, Inconsolata, Roboto, etc.) - Note: Your font dialog might get very long as >100 fonts will be added.<br />
<br />
=== Non-latin scripts ===<br />
<br />
==== Ancient Scripts ====<br />
<br />
* {{AUR|ttf-ancient-fonts}} - Font containing Unicode symbols for Aegean, Egyptian, Cuneiform, Anatolian, Maya, and Analecta scripts<br />
<br />
==== Arabic ====<br />
<br />
* {{AUR|ttf-amiri}} - A classical Arabic typeface in Naskh style poineered by Amiria Press<br />
* {{AUR|ttf-arabeyes-fonts}} - Collection of free Arabic fonts<br />
* {{AUR|ttf-qurancomplex-fonts}} - Fonts by King Fahd Glorious Quran Printing Complex in al-Madinah al-Munawwarah<br />
* {{AUR|ttf-sil-lateef}} - Unicode Arabic font from [[wikipedia:SIL_International|SIL]]<br />
* {{AUR|ttf-sil-scheherazade}} - Unicode Arabic font from SIL (Alternative for Traditional Arabic font)<br />
<br />
==== Bengali ====<br />
<br />
Read [[Localization/Bengali#Fonts]] for details.<br />
<br />
==== Braille ====<br />
<br />
* {{AUR|ttf-ubraille}} - Font containing Unicode symbols for ''braille''<br />
<br />
==== Chinese, Japanese, Korean, Vietnamese ====<br />
<br />
===== Pan-CJK =====<br />
<br />
* Adobe Source Han fonts - Large collection of fonts which comprehensively support Simplified Chinese, Traditional Chinese, Japanese, and Korean, with a consistent design and look.<br />
** {{Pkg|adobe-source-han-sans-otc-fonts}} - Sans fonts<br />
** {{Pkg|adobe-source-han-serif-otc-fonts}} - Serif fonts<br />
* {{Pkg|noto-fonts-cjk}} - Large collection of fonts which comprehensively support Simplified Chinese, Traditional Chinese, Japanese, and Korean, with a consistent design and look. It is currently a rebadged version of {{Pkg|adobe-source-han-sans-otc-fonts}}.<br />
<br />
===== Chinese =====<br />
<br />
See [[Localization/Chinese#Fonts]].<br />
<br />
===== Japanese =====<br />
<br />
See [[Localization/Japanese#Fonts]].<br />
<br />
===== Korean =====<br />
<br />
See [[Localization/Korean#Fonts]].<br />
<br />
===== Vietnamese =====<br />
<br />
* {{Pkg|ttf-hannom}} - Vietnamese TrueType font for chữ Nôm characters<br />
<br />
==== Cyrillic ====<br />
<br />
See also [[#Latin script]].<br />
<br />
* {{AUR|ttf-paratype}} - Font family by ParaType: sans, serif, mono, extended cyrillic and latin, OFL license<br />
* {{AUR|otf-russkopis}} - A free OpenType cursive font for Cyrillic script<br />
<br />
==== Greek ====<br />
<br />
Almost all Unicode fonts contain the Greek character set (polytonic included). Some additional font packages, which might not contain the complete Unicode set but utilize high quality Greek (and Latin, of course) typefaces are:<br />
<br />
* {{AUR|otf-gfs}} - Selection of OpenType fonts from the Greek Font Society<br />
* {{AUR|ttf-mgopen}} - Professional TrueType fonts from Magenta<br />
<br />
==== Hebrew ====<br />
<br />
* {{AUR|opensiddur-hebrew-fonts}} - Large collection of Open-source licensed Hebrew fonts. There are also few Latin, Greek, Cyrillic, Arabic, and Amharic.<br />
* {{AUR|culmus}} - Nice collection of free Hebrew fonts.<br />
* {{AUR|alefbet}} - 2 Hebrew fonts (at the moment): the commonly used "David Libre", and the handwriting font "Gveret Levin".<br />
* {{AUR|ttf-ms-fonts}} - contains Arial and other fonts.<br />
<br />
==== Indic ====<br />
<br />
See [[Localization/Indic#Fonts]].<br />
<br />
==== Khmer ====<br />
<br />
* {{Pkg|ttf-khmer}} - Font covering glyphs for Khmer language<br />
* [https://www.google.com/fonts/specimen/Hanuman Hanuman] ({{AUR|ttf-google-fonts-git}})<br />
<br />
==== Mongolic and Tungusic ====<br />
<br />
* {{AUR|ttf-abkai}} - Fonts for Sibe, Manchu and Daur scripts (incomplete, currently in development)<br />
<br />
==== Persian ====<br />
<br />
* {{AUR|persian-fonts}} - Meta package for installing all Persian fonts in AUR.<br />
* {{AUR|borna-fonts}} - Borna Rayaneh Co. Persian B font series.<br />
* {{AUR|iran-nastaliq-fonts}} - A free Unicode calligraphic Persian font.<br />
* {{AUR|iranian-fonts}} - Iranian-Sans and Iranian-Serif Persian font family.<br />
* {{AUR|ir-standard-fonts}} - Iran Supreme Council of Information and Communication Technology (SCICT) standard Persian fonts.<br />
* {{AUR|persian-hm-ftx-fonts}} - A Persian font series derived from X Series 2, Metafont and FarsiTeX fonts with Kashida feature.<br />
* {{AUR|persian-hm-xs2-fonts}} - A Persian font series derived from X Series 2 fonts with Kashida feature.<br />
* {{AUR|gandom-fonts}}, {{AUR|parastoo-fonts}}, {{AUR|sahel-fonts}}, {{AUR|samim-fonts}}, {{AUR|shabnam-fonts}}, {{AUR|tanha-fonts}}, {{AUR|vazir-fonts}}, {{AUR|vazir-code-fonts}} - Beautiful Persian fonts made by Saber RastiKerdar.<br />
* {{AUR|ttf-yas}} - The Yas Persian font series (with '''hollow zero''').<br />
* {{AUR|ttf-x2}} - Free fonts with support for Persian, Arabic, Urdu, Pashto, Dari, Uzbek, Kurdish, Uighur, old Turkish (Ottoman) and modern Turkish (Roman).<br />
<br />
==== Tai–Kadai ====<br />
<br />
* {{AUR|fonts-tlwg}} - Collection of scalable Thai fonts<br />
* {{AUR|ttf-lao}} - Lao TTF font (Phetsarath_OT)<br />
* {{AUR|ttf-lao-fonts}} - Lao TTF fonts, both Unicode and non-Unicode for Windows<br />
<br />
==== Tibeto-Burman ====<br />
<br />
* {{Pkg|ttf-tibetan-machine}} - Tibetan Machine TTFont<br />
* {{AUR|ttf-myanmar-fonts}} - 121 Fonts from myordbok.com<br />
<br />
=== Emoji and symbols ===<br />
<br />
A section of the Unicode standard is designated for pictographic characters called "emoji".<br />
<br />
[[Wikipedia:Emoji|Emoji]] fonts come in different formats: CBDT/CBLC (Google), SBIX (Apple), COLR/CPAL (Microsoft), SVG (Mozilla/Adobe).<br />
<br />
Emojis should work without any configuration once you have at least one emoji font installed of supported format. Emoji font fallback according to [[Wikipedia:Emoji#Emoji versus text presentation|the standard]] requires [https://github.com/google/emoji-segmenter extra code to handle emoji]. To force emoji font for specific application, see [[Font configuration#Force emoji font]].<br />
<br />
To actually type emojis, you'll need to install {{AUR|emote}} or the [https://snapcraft.io/install/emote/arch#:~:text=Launch%20the%20emoji%20picker%20with,into%20the%20currently%20focussed%20app. Emote Snap package]; or {{AUR|emoji-keyboard}} or the [https://github.com/OzymandiasTheGreat/emoji-keyboard/releases emoji-keyboard AppImage].<br />
<br />
{| class="wikitable"<br />
|-<br />
! Software !! CBDT/CBLC !! SBIX !! COLR/CPAL !! SVG !! Emoji font fallback<br />
|-<br />
! [[Wikipedia:Freetype|Freetype]]<br />
| {{Yes}} || {{Yes}} || {{Yes}} || {{No|https://savannah.nongnu.org/bugs/?46141}} || {{-}}<br />
|-<br />
! [[Wikipedia:Pango|Pango]]<br />
| colspan=4 {{C|Freetype}} || {{Yes|https://gitlab.gnome.org/GNOME/pango/-/issues/298}}<br />
|-<br />
! [[List of applications/Internet#WebKit-based|WebKitGTK]]<br />
| colspan=4 {{C|Freetype}} || {{Yes|https://trac.webkit.org/changeset/239822/webkit}}<br />
|-<br />
! [[Qt]]<br />
| colspan=4 {{C|Freetype}} || {{No}} [https://bugreports.qt.io/browse/QTBUG-71568] [https://bugreports.qt.io/browse/QTBUG-85014] [https://bugreports.qt.io/browse/QTBUG-85744] <br />
|-<br />
! [[Chromium]]<br />
| colspan=4 {{C|Freetype}} || {{Yes|https://chromium.googlesource.com/chromium/src.git/+/671511b00e2d6c374a3079c1c379d2d0dfad32fe}}<br />
|-<br />
! [[Firefox]]<br />
| colspan=3 {{C|Freetype}} || {{Yes}} || {{No|1=https://bugzilla.mozilla.org/show_bug.cgi?id=1509988}}, see [[Firefox#Font troubleshooting]] for workaround.<br />
|}<br />
<br />
CBDT/CBLC:<br />
<br />
* {{Pkg|noto-fonts-emoji}} — Google's open-source Emoji 13.1.<br />
* {{Pkg|ttf-joypixels}} — EmojiOne creator's proprietary Emoji 13.1.<br />
* {{AUR|ttf-twemoji}} — Twitter's open-source Emoji 13.0.<br />
<br />
SVG:<br />
<br />
* {{AUR|otf-openmoji}} — German University of Design in Schwäbisch Gmünd open-source Emoji 13.0.<br />
* {{AUR|ttf-twemoji-color}} — Twitter's open-source Emoji 13.0.<br />
<br />
Outline only:<br />
<br />
* {{AUR|ttf-symbola}} — provides many Unicode symbols, including emoji.<br />
<br />
[[wikipedia:Emoticon#Japanese_style|Kaomoji]] are sometimes referred to as "Japanese emoticons" and are composed of characters from various character sets, including CJK and Indic fonts. For example, the following set of packages covers most of existing kaomoji: {{Pkg|gnu-free-fonts}}, {{Pkg|ttf-arphic-uming}}, and {{Pkg|ttf-indic-otf}}.<br />
<br />
=== Math ===<br />
<br />
* {{Pkg|texlive-core}} and {{Pkg|texlive-fontsextra}} contain many math fonts such as Latin Modern Math and [[Wikipedia:STIX Fonts project|STIX Fonts]]. See [[TeX Live#Making fonts available to Fontconfig]] for configuration.<br />
* {{AUR|otf-stix}} - A standalone, more recent version of STIX<br />
* {{Pkg|otf-latin-modern}}, {{Pkg|otf-latinmodern-math}} - Improved version of Computer Modern fonts as used in LaTeX<br />
* {{AUR|ttf-computer-modern-fonts}}, {{AUR|otf-cm-unicode}} - [[wikipedia:Computer Modern|Computer Modern]] (of TeX fame)<br />
* {{AUR|ttf-mathtype}} - MathType fonts<br />
<br />
=== Other operating system fonts ===<br />
<br />
* {{AUR|ttf-mac-fonts}} - Apple MacOS TrueType fonts<br />
<br />
See [[Metric-compatible fonts]], which lists available alternatives for [[Microsoft fonts]].<br />
<br />
== Fallback font order ==<br />
<br />
Fontconfig automatically chooses a font that matches the current requirement. That is to say, if one is looking at a window containing English and Chinese for example, it will switch to another font for the Chinese text if the default one does not support it.<br />
<br />
Fontconfig lets every user configure the order they want via {{ic|$XDG_CONFIG_HOME/fontconfig/fonts.conf}}.<br />
If you want a particular Chinese font to be selected after your favorite Serif font, your file would look like this:<br />
<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>serif</family><br />
<prefer><br />
<family>Your favorite Latin Serif font name</family><br />
<family>Your Chinese font name</family><br />
</prefer><br />
</alias><br />
</fontconfig><br />
<br />
{{Tip|<br />
* If you use a Chinese locale, set {{ic|LC_LANG}} to {{ic|und}} to make this work. Otherwise both English and Chinese text will be rendered in the Chinese font.<br />
* After changing the configuration run {{ic|fc-match -a monospace {{!}} head}} to verify your fallback font is set correctly.<br />
}}<br />
<br />
You can add a section for sans-serif and monospace as well. For more information, have a look at the fontconfig manual.<br />
<br />
See also [[Font configuration#Replace or set default fonts]].<br />
<br />
== Font alias ==<br />
<br />
There are several font aliases which represent other fonts in order that applications may use similar fonts. The most common aliases are: {{ic|serif}} for a font of the serif type (e.g. DejaVu Serif); {{ic|sans-serif}} for a font of the sans-serif type (e.g. DejaVu Sans); and {{ic|monospace}} for a monospaced font (e.g. DejaVu Sans Mono). However, the fonts which these aliases represent may vary and the relationship is often not shown in font management tools, such as those found in [[KDE]] and other [[desktop environments]].<br />
<br />
To reverse an alias and find which font it is representing, run:<br />
<br />
{{hc|$ fc-match monospace|<br />
DejaVuSansMono.ttf: "DejaVu Sans Mono" "Book"<br />
}}<br />
<br />
In this case, {{ic|DejaVuSansMono.ttf}} is the font represented by the monospace alias.<br />
<br />
== Tips and tricks ==<br />
<br />
=== List all installed fonts ===<br />
<br />
You can use the following command to list all installed Fontconfig fonts that are available on your system. <br />
<br />
$ fc-list<br />
<br />
=== List installed fonts for a particular language ===<br />
<br />
Applications and browsers select and display fonts depending upon fontconfig preferences and available font glyph for Unicode text. To list installed fonts for a particular language, issue a command {{ic|1=fc-list :lang="''two letter language code''"}}. For instance, to list installed Arabic fonts or fonts supporting Arabic glyph:<br />
<br />
{{hc|1=$ fc-list -f '%{file}\n' :lang=ar|2=<br />
/usr/share/fonts/TTF/FreeMono.ttf<br />
/usr/share/fonts/TTF/DejaVuSansCondensed.ttf<br />
/usr/share/fonts/truetype/custom/DroidKufi-Bold.ttf<br />
/usr/share/fonts/TTF/DejaVuSansMono.ttf<br />
/usr/share/fonts/TTF/FreeSerif.ttf<br />
}}<br />
<br />
=== List installed fonts for a particular Unicode character ===<br />
<br />
To search for monospace fonts supporting a particular Unicode codepoint:<br />
<br />
$ fc-match -s monospace:charset=1F4A9<br />
<br />
=== Set terminal font on-the-fly ===<br />
<br />
{{Expansion|Where is the documentation for the escape codes?}}<br />
<br />
For terminal emulators that use [[X resources]], e.g. [[xterm]] or [[rxvt-unicode]], fonts can be set by using [[Bash/Prompt_customization#Bash_escape_sequences|escape sequences]]. Specifically, {{ic|echo -e "\033]710;$font\007"}} to change the normal font ({{ic|*font}} in {{ic|~/.Xresources}}), and replace {{ic|710}} with {{ic|711}}, {{ic|712}}, and {{ic|713}} to change the {{ic|*boldFont}}, {{ic|*italicFont}}, and {{ic|*boldItalicFont}}, respectively.<br />
<br />
{{ic|$font}} uses the same syntax as in {{ic|~/.Xresources}} and can be anything the terminal emulator will support. (Example: {{ic|1=xft:dejavu sans mono:size=9}})<br />
<br />
=== Application-specific font cache ===<br />
<br />
Matplotlib ({{Pkg|python-matplotlib}} or {{AUR|python2-matplotlib}}) uses its own font cache, so after updating fonts, be sure to remove {{ic|~/.matplotlib/fontList.cache}}, {{ic|~/.cache/matplotlib/fontList.cache}}, {{ic|~/.sage/matplotlib-1.2.1/fontList.cache}}, etc. so it will regenerate its cache and find the new fonts [http://matplotlib.1069221.n5.nabble.com/getting-matplotlib-to-recognize-a-new-font-td40500.html].<br />
<br />
=== BiDirectional text in terminal ===<br />
Run BiCon ({{AUR|bicon-git}}) in order to display correctly Arabic and Hebrew text inside the terminal.<br />
<br />
== See also ==<br />
<br />
* [http://behdad.org/text/ State of Text Rendering]<br />
* [https://fontlibrary.org/en Font Library] - Fonts under Free licenses<br />
* [https://screenshots.debian.net/packages?search=fonts&show=with Fonts on screenshots.debian.net]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Cursor_themes&diff=685414Cursor themes2021-07-05T00:22:03Z<p>Thiagowfx: /* Cursor size doesn't change on startup */ && -> &</p>
<hr />
<div>[[Category:X server]]<br />
[[Category:Eye candy]]<br />
[[de:Mauscursor-Themes]]<br />
[[es:Cursor themes]]<br />
[[it:Cursor themes]]<br />
[[ja:カーソルテーマ]]<br />
[[pt:Cursor themes]]<br />
[[ru:Cursor themes]]<br />
[[zh-hans:Cursor themes]]<br />
The display server is accompanied by a ''cursor theme'' that helps various aspects of GUI navigation and manipulation. The display server includes a cursor theme, however, other cursor themes can be installed and selected.<br />
<br />
== Installation ==<br />
<br />
Installation can be done with a package, or downloaded and extracted to an appropriate directory.<br />
<br />
=== Packages ===<br />
<br />
Cursors themes are available in the:<br />
<br />
* [[Official repositories]] — [https://archlinux.org/packages/?sort=&q=xcursor-&maintainer=&last_update=&flagged=&limit=50 "xcursor-" search].<br />
* [[AUR]] — [https://aur.archlinux.org/packages.php?O=0&L=0&C=17&K=cursor&SeB=nd&SB=n&SO=a&PP=50&do_Search=Go "cursor" search].<br />
<br />
=== Manually ===<br />
<br />
If a cursor theme is not available in the official repositories or the AUR, it can be added manually. A number of websites exist where cursor themes can be downloaded. Once downloaded, they need to be put in the ''icons'' directory (as cursors have the ability to be bundled with icon themes).<br />
<br />
Some websites that have cursor themes:<br />
<br />
* [https://www.gnome-look.org/browse/cat/107/ord/latest/ GNOME Look]<br />
* [https://www.deviantart.com/browse/all/customization/skins/linuxutil/x11cursors/ Deviant Art]<br />
* [https://www.opendesktop.org/browse/cat/107/ Open Desktop]<br />
<br />
For ''user-specific'' installation, use the {{ic|~/.local/share/icons/}} or {{ic|~/.icons/}} directory. Extract them with this command that will work for most archives:<br />
<br />
$ tar xvf foobar-cursor-theme.tar.gz -C ~/.local/share/icons<br />
<br />
The cursor theme directory structure is {{ic|theme-name/cursors}}, for example: {{ic|~/.local/share/icons/''theme''/cursors/}}; make sure the extracted files follow this structure.<br />
<br />
{{Note|For ''system-wide'' installation the {{ic|/usr/share/icons}} directory is used. Direct extraction to this directory is usually discouraged as files here are not tracked by [[pacman]]; it is recommended to create a [[PKGBUILD|package]] for the cursor theme instead.}}<br />
<br />
Already installed cursor themes can be viewed with the command:<br />
<br />
find /usr/share/icons ~/.local/share/icons ~/.icons -type d -name "cursors"<br />
<br />
If the package includes an {{ic|index.theme}} file, check if there is an "Inherits" line inside. If yes, check whether the inherited theme also exists on the system (rename if needed).<br />
<br />
== Configuration ==<br />
<br />
There are various ways to set the cursor theme.<br />
<br />
=== XDG specification ===<br />
<br />
This method applies to both [[X11]] and [[Wayland]] cursor themes. <br />
<br />
For ''user-specific'' configuration, create or edit {{ic|~/.icons/default/index.theme}}; for ''system-wide'' configuration, one can edit {{ic|/usr/share/icons/default/index.theme}}.<br />
<br />
The {{ic|Inherits}} option in the {{ic|[icon theme]}} section must be set to the xcursor theme directory name {{ic|''cursor_theme_name''}}, for example {{ic|xcursor-breeze-snow}}:<br />
<br />
{{hc|~/.icons/default/index.theme|2=<br />
[icon theme] <br />
Inherits=''cursor_theme_name''}}<br />
<br />
You should then edit {{ic|~/.config/gtk-3.0/settings.ini}}, replacing the {{ic|''cursor_theme_name''}} with the chosen one: <br />
<br />
{{hc|~/.config/gtk-3.0/settings.ini|2=<br />
[Settings]<br />
gtk-cursor-theme-name=''cursor_theme_name''}}<br />
<br />
Restart X for the changes to take effect.<br />
<br />
If it still doesn't work, try creating a symlink from {{ic|~/.icons/default/cursors}} (assuming ''user-specific'') to {{ic|.local/share/icons/''cursor_theme_name''/cursors}} and restart X again.<br />
<br />
=== LXAppearance ===<br />
<br />
[[LXDE#Cursors|LXAppearance]] sets the default cursor by creating an {{ic|~/.icons/default/index.theme}} file: if you edited that file manually, LXAppearance will overwrite it. Remember to also edit {{ic|~/.config/gtk-3.0/settings.ini}} manually as specified in [[#XDG specification]], because applications like Firefox use this setting instead.<br />
<br />
=== Desktop environments ===<br />
<br />
[[Desktop environments]] use the [https://specifications.freedesktop.org/xsettings-spec/xsettings-latest.html XSETTINGS protocol], typically implemented through a settings daemon. While this allows to change the cursor on-the-fly, the applied theme may be inconsistent across applications. See [[#XDG specification]] to change the cursor theme manually.<br />
<br />
==== GNOME ====<br />
<br />
To change the theme in [[GNOME]], use {{Pkg|gnome-tweaks}} or set the configuration directly with:<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-theme ''cursor_theme_name''<br />
<br />
Change the cursor size with (depending on the theme, sizes are 24, 32, 48, 64):<br />
<br />
$ gsettings set org.gnome.desktop.interface cursor-size ''cursor_theme_size''<br />
<br />
{{Note|By default, on Wayland, Gnome applications should be unable to display your cursor themes located in {{ic|~/.local/share/icons}}. As a workaround, you can [[#Environment_variable|add that path to XCURSOR_PATH]].}}<br />
<br />
==== MATE ====<br />
<br />
In MATE one can use mate-control-center or gsettings. To change the theme:<br />
<br />
gsettings set org.mate.peripherals-mouse cursor-theme ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
gsettings set org.mate.peripherals-mouse ''theme-size''<br />
<br />
==== XFCE ====<br />
<br />
To change the xcursor theme, use:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeName --set ''cursor_theme_name''<br />
<br />
To change the size:<br />
<br />
xfconf-query --channel xsettings --property /Gtk/CursorThemeSize --set ''cursor_theme_size''<br />
<br />
=== X resources ===<br />
<br />
To locally name a cursor theme, add to the {{ic|~/.Xresources}} file:<br />
<br />
Xcursor.theme: cursor-theme<br />
<br />
To have the cursor theme properly loaded it will need to be done so by the window manager; if it does not, it can be forced to load prior the window manager by putting the following command in {{ic|~/.xinitrc}} or [[.xprofile]] (depending on ones personal setup):<br />
<br />
$ xrdb ~/.Xresources<br />
<br />
Optionally, add this line to {{ic|~/.Xresources}} if your cursor theme supports multiple sizes:<br />
<br />
Xcursor.size: 16<br />
<br />
{{Tip|32, 48 or 64 may also be good size.}}<br />
<br />
If in doubt over supported cursor sizes, start X without this setting and let it choose the cursor size automatically. (Refer to your window manager documentation for details.)<br />
<br />
=== Environment variable ===<br />
<br />
You can use an [[environment variable]] to set a theme for a single application to try it out temporarily, for example:<br />
<br />
$ XCURSOR_THEME=SomeThemeName xclock<br />
<br />
XCURSOR_SIZE is optional if your cursor theme supports multiple sizes.<br />
<br />
If cursor themes are installed in {{ic|~/.local/share/icons}}, in order to avoid possible issues, add that path to XCURSOR_PATH. For example:<br />
<br />
{{hc|~/.bash_profile|2=<br />
export XCURSOR_PATH=${XCURSOR_PATH}:~/.local/share/icons}}<br />
<br />
=== Display managers ===<br />
<br />
Cursor theme can usually be set within a display manager, but keep in mind the cursor theme may not carry over to the user session. <br />
<br />
==== GDM ====<br />
<br />
See [[GDM#Changing the cursor theme]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Create links to missing cursors ===<br />
<br />
Applications may keep using the default cursors when a theme lacks some cursors. This can be corrected by adding links to the missing cursors. For example:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ ln -s right_ptr arrow<br />
$ ln -s cross crosshair<br />
$ ln -s right_ptr draft_large<br />
$ ln -s right_ptr draft_small<br />
$ ln -s cross plus<br />
$ ln -s left_ptr top_left_arrow<br />
$ ln -s cross tcross<br />
$ ln -s hand hand1<br />
$ ln -s hand hand2<br />
$ ln -s left_side left_tee<br />
$ ln -s left_ptr ul_angle<br />
$ ln -s left_ptr ur_angle<br />
$ ln -s left_ptr_watch 08e8e1c95fe2fc01f976f1e063a24ccd<br />
<br />
If the above does not solve the problem, look in {{ic|/usr/share/icons/whiteglass/cursors}} for additional cursors your theme may be missing, and create links for these as well.<br />
<br />
{{Tip|You can also remove unwanted cursors. To for example remove the "watch" cursor:<br />
<br />
$ cd ~/.icons/''theme''/cursors/<br />
$ rm watch left_ptr_watch<br />
$ ln -s left_ptr watch<br />
$ ln -s left_ptr left_ptr_watch<br />
}}<br />
<br />
=== Supplying missing cursors ===<br />
<br />
Some programs set their own custom cursors {{ic|~/.Xresources}} which you may want to override. A common example of this is rdesktop, which connects to a Microsoft Windows computer and uses the cursors obtained from the remote machine, which can often be difficult to see due to protocol limitations yielding poor conversion quality.<br />
<br />
This can be resolved by replacing these cursors with ones from the same (or another) cursor theme. In order to do this, the '''hash''' of the image must be obtained. This is done by setting the {{ic|XCURSOR_DISCOVER}} environment variable prior to launching the application that sets these cursors:<br />
<br />
$ XCURSOR_DISCOVER=1 rdesktop ...<br />
<br />
The first time (and only the first time) the cursor is set, some details will be displayed, like this:<br />
<br />
Cursor image name: 24020000002800000528000084810000<br />
...<br />
Cursor image name: 7bf1cc07d310bf080118007e08fc30ff<br />
...<br />
Cursor hash 24020000002800000528000084810000 returns 0x0<br />
<br />
When Xcursor looks for missing cursors, the search path includes {{ic|~/.icons/default/cursors}} so this is where an image can be placed for Xcursor to find. First, create this directory if it does not already exist:<br />
<br />
$ mkdir -p ~/.icons/default/cursors<br />
<br />
Then link the hash to the target image. Here we are using the {{ic|left_ptr}} image from the {{ic|Vanilla-DMZ}} cursor theme:<br />
<br />
$ ln -s /usr/share/icons/Vanilla-DMZ/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000<br />
<br />
The change will be visible as soon as the application is restarted. No special method of launching the application is required.<br />
<br />
==== rdesktop ====<br />
<br />
Here are some common Microsoft Windows cursors that rdesktop uses when connecting to a remote machine running Windows 7. Unfortunately, animated cursors are difficult to override as they are sent frame-by-frame, so one mapping will be needed for every frame!<br />
<br />
$ ln -s /usr/share/icons/$THEME/cursors/xterm ~/.icons/default/cursors/00000000017e000002fc000000000000<br />
$ ln -s /usr/share/icons/$THEME/cursors/right_ptr ~/.icons/default/cursors/00000093000010860000631100006609<br />
$ ln -s /usr/share/icons/$THEME/cursors/plus ~/.icons/default/cursors/01e00000201c00004038000080300000<br />
$ ln -s /usr/share/icons/$THEME/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000<br />
$ ln -s /usr/share/icons/$THEME/cursors/left_ptr_watch ~/.icons/default/cursors/6ce0180090108e0005814700a0021400<br />
$ ln -s /usr/share/icons/$THEME/cursors/hand ~/.icons/default/cursors/d2201000a2c622004385440041308800<br />
$ ln -s /usr/share/icons/$THEME/cursors/watch ~/.icons/default/cursors/fc618c00da110f0034fd0e004e082400<br />
<br />
=== Change X shaped default cursor ===<br />
<br />
The default X shaped Xcursor appears in window managers that do not set the default cursor to left_ptr or in window managers using XCB (like [[awesome]]) instead of Xlib.<br />
<br />
To fix this simply add the following to your {{ic|~/.xinitrc}} , xsession or window managers startup configuration if possible (for example bspwm's bspwmrc). <br />
$ xsetroot -cursor_name left_ptr<br />
<br />
The list of cursor styles is in [https://tronche.com/gui/x/xlib/appendix/b/ appendix B] of the X protocol.<br />
<br />
=== .Xdefaults ===<br />
<br />
If you have conflicting cursors then it might be because a different cursor has been set in the {{ic|~/.Xdefaults}} file.<br />
<br />
=== Cursor size doesn't change on startup ===<br />
<br />
If you are trying to change cursor size via {{ic|~/.Xresources}} in your {{ic|~/.xinitrc}} and it doesn't work, make sure that xrandr runs before loading {{ic|~/.Xresources}}.<br />
<br />
Make sure your {{ic|~/.xinitrc}} looks similar to the following<br />
<br />
{{hc|~/.xinitrc|2=<br />
xrandr &<br />
...<br />
xrdb -merge ~/.Xresources &<br />
exec ''wm''}}<br />
<br />
== See also ==<br />
<br />
* {{man|3|Xcursor}} — For more information about cursors in X (supported directories, formats, compatibility, etc.).</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Systemd-boot&diff=684844Systemd-boot2021-07-01T19:16:03Z<p>Thiagowfx: /* Grml on ESP */ add aur package reference</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Boot loaders]]<br />
[[de:Systemd-boot]]<br />
[[es:Systemd-boot]]<br />
[[ja:Systemd-boot]]<br />
[[pt:Systemd-boot]]<br />
[[ru:Systemd-boot]]<br />
[[zh-hans:Systemd-boot]]<br />
{{Related articles start}}<br />
{{Related|Arch boot process}}<br />
{{Related|Secure Boot}}<br />
{{Related|Unified Extensible Firmware Interface}}<br />
{{Related articles end}}<br />
<br />
'''systemd-boot''', previously called '''gummiboot''' (German for: 'rubber dinghy'), is a simple UEFI [[boot manager]] which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu to be navigated via arrow-keys. It is included with {{pkg|systemd}}, which is installed on an Arch system by default.<br />
<br />
It is simple to configure but it can only start EFI executables such as the Linux kernel [[EFISTUB]], [[UEFI shell]], GRUB, or the Windows Boot Manager.<br />
<br />
== Installation ==<br />
<br />
=== Installing the EFI boot manager ===<br />
<br />
To install the ''systemd-boot'' EFI boot manager, first make sure the system has booted in UEFI mode and that [[Unified Extensible Firmware Interface#UEFI variables|UEFI variables]] are accessible. This can be checked by running the command {{ic|efivar --list}} or, if {{Pkg|efivar}} is not installed, by doing {{ic|ls /sys/firmware/efi/efivars}} (if the directory exists, the system is booted in UEFI mode).<br />
<br />
{{ic|''esp''}} will be used throughout this page to denote the [[EFI system partition#Typical mount points|ESP mountpoint]], e.g. {{ic|/boot}} or {{ic|/efi}}. This assumes that you have {{ic|chroot}}ed to your system's mount point.<br />
<br />
With the ESP mounted to {{ic|''esp''}}, use bootctl to install ''systemd-boot'' into the EFI system partition by running: <br />
<br />
# bootctl install<br />
<br />
This will copy the ''systemd-boot'' boot loader to the EFI partition: on a x64 architecture system {{ic|/usr/lib/systemd/boot/efi/systemd-bootx64.efi}} will be copied to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} and {{ic|''esp''/EFI/BOOT/BOOTX64.EFI}}. It will then set ''systemd-boot'' as the default EFI application (default boot entry) loaded by the EFI Boot Manager.<br />
<br />
{{Note|Installing systemd-boot will overwrite any existing {{ic|/EFI/BOOT/BOOTX64.EFI}}, for example Microsoft's version of this file.}}<br />
<br />
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.<br />
<br />
=== Installation using XBOOTLDR ===<br />
<br />
A separate {{ic|''boot''}} partition of type {{ic|"Linux extended boot"}} can be created to keep the kernel and initramfs separate from the {{ic|''esp''}} partition. XBOOTLDR [https://systemd.io/BOOT_LOADER_SPECIFICATION] must have a partition type GUID of {{ic|"bc13c2ff-59e6-4262-a352-b275fd6f7172"}}.<br />
<br />
This is particularly helpful to [[dual boot with Windows]] with an existing [[EFI system partition]] that is too small. Otherwise create an {{ic|''esp''}} partition as normal plus another for {{ic|''boot''}} on the same physical drive. The size of {{ic|''boot''}} should be enough to accommodate all of the kernels you are going to install.<br />
<br />
{{Note|<br />
* systemd-boot does not do a file system check like it does for the ESP. Hence, it is possible to use other file systems but only if your UEFI implementation can read it during boot.<br />
* A UEFI firmware may skip loading partitions other than the ESP when a "fast boot" mode is enabled. This can lead to "systemd-boot" failing to find entries on the XBOOTLDR partition. You may have to disable "fast boot" for XBOOTLDR to work.<br />
* The XBOOTLDR partition may need to be on the same physical disk as the ESP for systemd-boot to recognize it.<br />
}}<br />
<br />
During install mount {{ic|''esp''}} to {{ic|/mnt/efi}} and {{ic|''boot''}} to {{ic|/mnt/boot}}.<br />
<br />
Once in chroot use the command:<br />
<br />
# bootctl --esp-path=/efi --boot-path=/boot install<br />
<br />
To conclude the installation, [[#Configuration|configure]] ''systemd-boot''.<br />
<br />
=== Updating the EFI boot manager ===<br />
<br />
Whenever there is a new version of ''systemd-boot'', the boot manager can be optionally reinstalled by the user. This can be performed manually, or the update can be automatically triggered using pacman hooks. The two approaches are described thereafter.<br />
<br />
{{Note|The boot manager is a standalone EFI executable and any version can be used to boot the system (partial updates do not apply, since pacman only installs the systemd-boot installer, not systemd-boot itself). However, new versions may add new features or fix bugs, so it is probably a good idea to update it anyway.}}<br />
<br />
==== Manual update ====<br />
<br />
Use ''bootctl'' to update ''systemd-boot'':<br />
<br />
# bootctl update<br />
<br />
If the location of the ESP is non-standard (i.e., it is not {{ic|/efi}}, {{ic|/boot}}, or {{ic|/boot/efi}}), you need to explicitly provide it using the {{ic|1=--esp-path}} parameter.<br />
<br />
==== Automatic update ====<br />
<br />
The package {{AUR|systemd-boot-pacman-hook}} provides a [[Pacman hook]] to automate the update process. [[Install|Installing]] the package will add a hook which will be executed every time the {{Pkg|systemd}} package is upgraded.<br />
Alternatively, to replicate what the ''systemd-boot-pacman-hook'' package does without installing it, place the following pacman hook in the {{ic|/etc/pacman.d/hooks/}} directory:<br />
<br />
{{hc|/etc/pacman.d/hooks/100-systemd-boot.hook|2=<br />
[Trigger]<br />
Type = Package<br />
Operation = Upgrade<br />
Target = systemd<br />
<br />
[Action]<br />
Description = Updating systemd-boot<br />
When = PostTransaction<br />
Exec = /usr/bin/bootctl update<br />
}}<br />
<br />
If you have [[Secure Boot]] enabled, you may want to install a pacman hook to automatically re-sign the kernel and systemd-boot when the former is updated.<br />
<br />
{{hc|/etc/pacman.d/hooks/99-secureboot.hook|2=<br />
[Trigger]<br />
Operation = Install<br />
Operation = Upgrade<br />
Type = Package<br />
Target = linux<br />
Target = systemd<br />
<br />
[Action]<br />
Description = Signing Kernel for SecureBoot<br />
When = PostTransaction<br />
Exec = /usr/bin/find /boot -type f ( -name vmlinuz-* -o -name systemd* ) -exec /usr/bin/sh -c 'if ! /usr/bin/sbverify --list {} 2>/dev/null {{!}} /usr/bin/grep -q "signature certificates"; then /usr/bin/sbsign --key db.key --cert db.crt --output "$1" "$1"; fi' _ {} ;<br />
Depends = sbsigntools<br />
Depends = findutils<br />
Depends = grep<br />
}}<br />
<br />
The {{ic|Target}} needs to be duplicated each time you want to add a new package. With respect to the {{ic|find}} statement, since we had a condition with the filenames and ALPM hooks are being split on spaces, we had to surround the whole statement by quotes in order for the hook to be parsed properly. Since systemd-boot is located in sub-directories, the depth needed to be adjusted as well so that we removed the {{ic|-maxdepth}} argument. In order to avoid hassle, if you are unsure, try to reinstall the package you want to test to see if the hook and signing part are processed successfully. See [[Pacman#Hooks]] or {{man|5|alpm-hooks}} for more information.<br />
<br />
== Configuration ==<br />
<br />
=== Loader configuration ===<br />
<br />
The loader configuration is stored in the file {{ic|''esp''/loader/loader.conf}}.<br />
<br />
{{Remove|Duplicates {{man|5|loader.conf|OPTIONS}}.}}<br />
<br />
The following settings can be specified:<br />
<br />
* {{ic|default}} – default entry to select as defined in [[#Adding loaders]]; it can be a wildcard like {{ic|arch-*.conf}}.<br />
* {{ic|timeout}} – menu timeout in seconds before the default entry is booted. If this is not set, the menu will only be shown on {{ic|Space}} key (or most other keys actually work too) press during boot.<br />
* {{ic|editor}} – whether to enable the kernel parameters editor or not. {{ic|yes}} (default) is enabled, {{ic|no}} is disabled; since the user can add {{ic|1=init=/bin/bash}} to bypass root password and gain root access, it is strongly recommended to set this option to {{ic|no}} if the machine can be accessed by unauthorized persons.<br />
* {{ic|auto-entries}} – shows automatic entries for Windows, EFI Shell, and Default Loader if set to {{ic|1}} (default), {{ic|0}} to hide;<br />
* {{ic|auto-firmware}} – shows entry for rebooting into UEFI firmware settings if set to {{ic|1}} (default), {{ic|0}} to hide;<br />
* {{ic|console-mode}} – changes UEFI console mode:<br />
** {{ic|0}} for 80x25;<br />
** {{ic|1}} for 80x50;<br />
** {{ic|2}} and above for non-standard modes provided by the device firmware, if any;<br />
** {{ic|auto}} picks a suitable mode automatically;<br />
** {{ic|max}} for highest available mode;<br />
** {{ic|keep}} (default) for the firmware selected mode.<br />
* {{ic|random-seed-mode}} - controls whether to read the random seed from the file {{ic|''esp''/loader/random-seed}}. If set to {{ic|with-system-token}} (default), it loads the seed from file only if the EFI variable {{ic|LoaderSystemToken}} is set; if set to {{ic|always}}, it loads the seed from file even if the EFI variable is unset; and if set to {{ic|off}}, the file is ignored.<br />
For a detailed explanation of the available settings and their corresponding arguments see the {{man|5|loader.conf}} manual. A loader configuration example is provided below:<br />
<br />
{{hc|''esp''/loader/loader.conf|<br />
default arch.conf<br />
timeout 4<br />
console-mode max<br />
editor no<br />
}}<br />
<br />
{{Tip|<br />
* systemd-boot does not accept tabs for indentation, use spaces instead.<br />
* {{ic|default}} and {{ic|timeout}} can be changed in the boot menu itself and changes will be stored as EFI variables {{ic|LoaderEntryDefault}} and {{ic|LoaderConfigTimeout}}, overriding these options. <br />
* {{ic|bootctl set-default ""}} can be used to clear the EFI variable overriding the {{ic|default}} option.<br />
* A basic loader configuration file is located at {{ic|/usr/share/systemd/bootctl/loader.conf}}.<br />
}}<br />
<br />
=== Adding loaders ===<br />
<br />
''systemd-boot'' will search for boot menu items in {{ic|''esp''/loader/entries/*.conf}} and additionally in {{ic|''boot''/loader/entries/*.conf}} if using [[#Installation using XBOOTLDR|XBOOTLDR]]. Note that entries in ''esp'' can only use files (e.g. kernels, initramfs, images, etc.) in ''esp''. Similarly, entries in ''boot'' can only use files in ''boot''.<br />
<br />
{{Remove|Duplicates https://systemd.io/BOOT_LOADER_SPECIFICATION/#type-1-boot-loader-specification-entries.}}<br />
<br />
The possible options are:<br />
<br />
* {{ic|title}} – operating system name. '''Required.'''<br />
* {{ic|version}} – kernel version, shown only when multiple entries with same title exist. Optional.<br />
* {{ic|machine-id}} – machine identifier from {{ic|/etc/machine-id}}, shown only when multiple entries with same title and version exist. Optional.<br />
* {{ic|efi}} – EFI program to start, relative to your ESP ({{ic|''esp''}}); e.g. {{ic|/vmlinuz-linux}}. '''Either''' this parameter '''or''' {{ic|linux}} (see below) '''is required'''.<br />
* {{ic|options}} – space-separated command line options to pass to the EFI program or [[kernel parameters]]. Optional, but you will need at least {{ic|1=root=''dev''}} if booting Linux. This parameter can be omitted if the root partition is assigned the correct Root Partition Type GUID as defined in [https://systemd.io/DISCOVERABLE_PARTITIONS/ Discoverable Partitions Specification] and if the {{ic|systemd}} [[mkinitcpio]] hook is present.<br />
<br />
For Linux boot, you can also use {{ic|linux}} instead of {{ic|efi}}. Or {{ic|initrd}} in addition to {{ic|options}}. The syntax is:<br />
<br />
* {{ic|linux}} and {{ic|initrd}} followed by the relative path of the corresponding files in the ESP; e.g. {{ic|/vmlinuz-linux}}; this will be automatically translated into {{ic|efi ''path''}} and {{ic|1=options initrd=''path''}} – this syntax is only supported for convenience and has no differences in function.<br />
<br />
{{Note|If {{ic|options}} is present in a boot entry and [[Secure Boot]] is disabled, the value of {{ic|options}} will override any {{ic|.cmdline}} string embedded in the EFI image that is specified by {{ic|efi}} or {{ic|linux}} (see [[#Preparing a unified kernel image]]). With Secure Boot, however, {{ic|options}} (and any edits made to the kernel command line in the bootloader UI) will be ignored, and only the embedded {{ic|.cmdline}} will be used. }}<br />
<br />
An example of loader files launching Arch from a volume [[Persistent block device naming#by-label|labeled]] {{ic|''arch_os''}} and loading Intel CPU [[microcode]] is:<br />
<br />
{{hc|''esp''/loader/entries/arch.conf|2=<br />
title Arch Linux<br />
linux /vmlinuz-linux<br />
initrd /intel-ucode.img<br />
initrd /initramfs-linux.img<br />
options root="LABEL=''arch_os''" rw<br />
}}<br />
<br />
{{hc|''esp''/loader/entries/arch-fallback.conf|2=<br />
title Arch Linux (fallback initramfs)<br />
linux /vmlinuz-linux<br />
initrd /intel-ucode.img<br />
initrd /initramfs-linux-fallback.img<br />
options root="LABEL=''arch_os''" rw<br />
}}<br />
<br />
''systemd-boot'' will automatically check at boot time for '''Windows Boot Manager''' at the location {{ic|/EFI/Microsoft/Boot/Bootmgfw.efi}}, [[UEFI shell]] {{ic|/shellx64.efi}} and '''EFI Default Loader''' {{ic|/EFI/BOOT/bootx64.efi}}, as well as specially prepared kernel files found in {{ic|/EFI/Linux/}}. When detected, corresponding entries with titles {{ic|auto-windows}}, {{ic|auto-efi-shell}} and {{ic|auto-efi-default}}, respectively, will be generated. These entries do not require manual loader configuration. However, it does not auto-detect other EFI applications (unlike [[rEFInd]]), so for booting the Linux kernel, manual configuration entries must be created.<br />
<br />
{{Note|<br />
* If you dual-boot Windows, it is strongly recommended to disable its default [[Dual boot with Windows#Fast Startup and hibernation|Fast Startup]] option.<br />
* If you have an Intel or AMD CPU, load the [[microcode]] with {{ic|initrd}} ''before'' other images, an example is provided in [[Microcode#systemd-boot]].<br />
}}<br />
<br />
{{Tip|<br />
* The available boot entries which have been configured can be listed with the command {{ic|bootctl list}}.<br />
* An example entry file is located at {{ic|/usr/share/systemd/bootctl/arch.conf}}.<br />
* The [[kernel parameters]] for scenarios such as [[LVM]], [[LUKS]] or [[dm-crypt]] can be found on the relevant pages.<br />
}}<br />
<br />
==== EFI Shells or other EFI applications ====<br />
<br />
{{Expansion|If the UEFI shell is placed as {{ic|/shellx64.efi}} in the ESP, it will be autodetected. Using multiple UEFI shell versions is uncommon, so provide a better example with some other EFI application.}}<br />
<br />
In case you installed [[UEFI shell|EFI shells]] and [[rEFInd#Tools|other EFI application]] into the ESP, you can use the following snippets.<br />
<br />
{{Note|The file path parameter for the {{ic|efi}} line is relative to your ''esp'' mount point. If you are mounted on {{ic|/boot}} and your EFI binaries reside at {{ic|/boot/EFI/xx.efi}} and {{ic|/boot/yy.efi}}, then you would specify the parameters as {{ic|efi /EFI/xx.efi}} and {{ic|efi /yy.efi}} respectively.}}<br />
<br />
Examples of loading custom [[UEFI shell]] loaders:<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v1-x86_64.conf|<br />
title UEFI Shell x86_64 v1<br />
efi /EFI/shellx64_v1.efi<br />
}}<br />
<br />
{{hc|''esp''/loader/entries/uefi-shell-v2-x86_64.conf|<br />
title UEFI Shell x86_64 v2<br />
efi /EFI/shellx64_v2.efi<br />
}}<br />
<br />
=== Booting into EFI Firmware Setup ===<br />
<br />
Most system firmware configured for EFI booting will add its own [[efibootmgr]] entries to boot into UEFI Firmware Setup.<br />
<br />
=== Support hibernation ===<br />
<br />
See [[Suspend and hibernate]].<br />
<br />
=== Kernel parameters editor with password protection ===<br />
<br />
Alternatively you can install {{AUR|systemd-boot-password}} which supports {{ic|password}} basic configuration option. Use {{ic|sbpctl generate}} to generate a value for this option.<br />
<br />
Install ''systemd-boot-password'' with the following command:<br />
<br />
# sbpctl install ''esp''<br />
<br />
With enabled editor you will be prompted for your password before you can edit kernel parameters.<br />
<br />
== Keys inside the boot menu ==<br />
<br />
{{Remove|Duplicates {{man|7|systemd-boot|KEY BINDINGS}}.}}<br />
<br />
The following keys are used inside the menu:<br />
<br />
* {{ic|Up/Down}} - select entry<br />
* {{ic|Enter}} - boot the selected entry<br />
* {{ic|d}} - select the default entry to boot (stored in a non-volatile EFI variable)<br />
* {{ic|-/T}} - decrease the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|+/t}} - increase the timeout (stored in a non-volatile EFI variable)<br />
* {{ic|e}} - edit the kernel command line. It has no effect if the {{ic|editor}} config option is set to {{ic|0}}.<br />
* {{ic|v}} - show the systemd-boot and UEFI version<br />
* {{ic|Q}} - quit<br />
* {{ic|P}} - print the current configuration<br />
* {{ic|h/?}} - help<br />
<br />
These hotkeys will, when pressed inside the menu or during bootup, directly boot<br />
a specific entry:<br />
<br />
* {{ic|l}} - Linux<br />
* {{ic|w}} - Windows<br />
* {{ic|a}} - macOS<br />
* {{ic|s}} - EFI Shell<br />
* {{ic|1-9}} - number of entry<br />
<br />
See {{man|7|systemd-boot}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Choosing next boot ===<br />
<br />
The boot manager is integrated with the systemctl command, allowing you to choose what option you want to boot after a reboot. For example, suppose you have built a custom kernel and created an entry file {{ic|''esp''/loader/entries/arch-custom.conf}} to boot into it, you can just launch<br />
<br />
$ systemctl reboot --boot-loader-entry=arch-custom.conf<br />
<br />
and your system will reboot into that entry maintaining the default option intact for subsequent boots. To see a list of possible entries pass the {{ic|1=--boot-loader-entry=help}} option.<br />
<br />
If you want to boot into the firmware of your motherboard directly, then you can use this command:<br />
<br />
$ systemctl reboot --firmware-setup<br />
<br />
=== Preparing a unified kernel image ===<br />
<br />
systemd-boot searches in {{ic|''esp''/EFI/Linux/}} for [https://systemd.io/BOOT_LOADER_SPECIFICATION#type-2-efi-unified-kernel-images unified kernel images], which bundle the kernel, the init RAM disk (initrd), the kernel command line, {{ic|/etc/os-release}}, and a splash image into one single file. This file can be easily signed for [[Secure Boot]].<br />
<br />
Put the kernel command line you want to use in a file, and create the bundle file like this:<br />
<br />
{{bc|1=<br />
$ objcopy \<br />
--add-section .osrel="/usr/lib/os-release" --change-section-vma .osrel=0x20000 \<br />
--add-section .cmdline="/etc/kernel/cmdline" --change-section-vma .cmdline=0x30000 \<br />
--add-section .splash="/usr/share/systemd/bootctl/splash-arch.bmp" --change-section-vma .splash=0x40000 \<br />
--add-section .linux="vmlinuz-file" --change-section-vma .linux=0x2000000 \<br />
--add-section .initrd="initrd-file" --change-section-vma .initrd=0x3000000 \<br />
"/usr/lib/systemd/boot/efi/linuxx64.efi.stub" "''linux''.efi"<br />
}}<br />
<br />
Optionally [[Secure Boot#Signing EFI binaries|sign]] the {{ic|''linux''.efi}} file produced above.<br />
<br />
Copy {{ic|''linux''.efi}} into {{ic|''esp''/EFI/Linux/}}.<br />
<br />
=== Grml on ESP ===<br />
<br />
{{Note|The following instructions are not exclusive to Grml. With slight adjustments, installing other software (e.g., [https://www.system-rescue-cd.org/ SystemRescueCD]) is possible.}}<br />
<br />
{{Tip|A {{ic|PKGBUILD}} is available: {{Aur|grml-systemd-boot}}.}}<br />
<br />
[https://grml.org/ Grml] is a small live system with a collection of software for system administration and rescue.<br />
<br />
In order to install Grml on the ESP, we only need to copy the kernel {{ic|vmlinuz}}, the initramfs {{ic|initrd.img}}, and the squashed image {{ic|grml64-small.squashfs}} from the iso file to the ESP. To do so, first download [https://grml.org/ grml64-small.iso] and mount the file (the mountpoint is henceforth denoted ''mnt''); the kernel and initramfs are located in {{ic|''mnt''/boot/grml64small/}}, and the squashed image resides in {{ic|''mnt''/live/grml64-small/}}.<br />
<br />
Next, create a directory for Grml in your ESP,<br />
<br />
# mkdir -p ''esp''/grml<br />
<br />
and copy the above-mentioned files in there:<br />
<br />
# cp ''mnt''/boot/grml64small/vmlinuz ''esp''/grml<br />
# cp ''mnt''/boot/grml64small/initrd.img ''esp''/grml<br />
# cp ''mnt''/live/grml64-small/grml64-small.squashfs ''esp''/grml<br />
<br />
In the last step, create an entry for the systemd-boot loader: In {{ic|''esp''/loader/entries}} create a {{ic|grml.conf}} file with the following content:<br />
<br />
{{hc|''esp''/loader/entries/grml.conf|2=<br />
title Grml Live Linux<br />
linux /grml/vmlinuz<br />
initrd /grml/initrd.img<br />
options apm=power-off boot=live live-media-path=/grml/ nomce net.ifnames=0}}<br />
<br />
For an overview of the available boot options, consult the [https://git.grml.org/?p=grml-live.git;a=blob_plain;f=templates/GRML/grml-cheatcodes.txt;hb=HEAD cheatcode for Grml].<br />
<br />
=== systemd-boot on BIOS systems ===<br />
<br />
If you need a bootloader for BIOS systems that follows [https://systemd.io/BOOT_LOADER_SPECIFICATION/ The Boot Loader Specification], then systemd-boot can be pressed into service on BIOS systems. The [[Clover]] boot loader supports booting from BIOS systems and provides a simulated EFI environment.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Installing after booting in BIOS mode ===<br />
<br />
{{Warning|This is not recommended.}}<br />
<br />
If booted in BIOS mode, you can still install ''systemd-boot'', however this process requires you to tell firmware to launch ''systemd-boot'''s EFI file at boot, usually via two ways:<br />
<br />
* you have a working EFI Shell somewhere else.<br />
* your firmware interface provides a way of properly setting the EFI file that needs to be loaded at boot time.<br />
<br />
If you can do it, the installation is easier: go into your EFI Shell or your firmware configuration interface and change your machine's default EFI file to {{ic|''esp''/EFI/systemd/systemd-bootx64.efi}} (or {{ic|systemd-bootia32.efi}} depending if your system firmware is 32 bit).<br />
<br />
{{Note|The firmware interface of Dell Latitude series provides everything you need to setup EFI boot but the EFI Shell will not be able to write to the computer's ROM.}}<br />
<br />
=== Manual entry using efibootmgr ===<br />
<br />
If the {{ic|bootctl install}} command failed, you can create a EFI boot entry manually using {{Pkg|efibootmgr}}:<br />
<br />
# efibootmgr --create --disk /dev/sd''X'' --part ''Y'' --loader "\EFI\systemd\systemd-bootx64.efi" --label "Linux Boot Manager" --verbose<br />
<br />
where {{ic|/dev/sd''XY''}} is the [[EFI system partition]].<br />
<br />
{{Note|The path to the EFI image must use the backslash ({{ic|\}}) as the separator}}<br />
<br />
=== Manual entry using bcdedit from Windows ===<br />
<br />
If for any reason you need to create an EFI boot entry from Windows, you can use the following commands from an Administrator prompt:<br />
<br />
# bcdedit /copy {bootmgr} /d "Linux Boot Manager"<br />
# bcdedit /set {guid} path \EFI\systemd\systemd-bootx64.efi<br />
<br />
Replace {{ic|{guid} }} with the id returned by the first command. You can also set it as the default entry using<br />
<br />
# bcdedit /default {guid}<br />
<br />
=== Menu does not appear after Windows upgrade ===<br />
<br />
See [[UEFI#Windows changes boot order]].<br />
<br />
== See also ==<br />
<br />
* https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/<br />
* https://github.com/systemd/systemd/tree/master/src/boot/efi<br />
* https://bbs.archlinux.org/viewtopic.php?id=254374<br />
* https://systemd.io/BOOT_LOADER_SPECIFICATION/</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Keyboard_shortcuts&diff=684557Keyboard shortcuts2021-06-30T00:33:06Z<p>Thiagowfx: /* Xorg and Wayland */ use a more logical order in shortcut example</p>
<hr />
<div>[[Category:Keyboard configuration]]<br />
[[Category:X server]]<br />
[[Category:Accessibility]]<br />
[[fr:Keyboard shortcuts]]<br />
[[ja:キーボードショートカット]]<br />
[[pt:Keyboard shortcuts]]<br />
[[ru:Keyboard shortcuts]]<br />
[[zh-hans:Keyboard shortcuts]]<br />
This article provides a list of (not commonly known) default keyboard shortcuts and provides information about user customization.<br />
<br />
== Standard shortcuts ==<br />
<br />
=== Kernel (SysRq) ===<br />
<br />
There are several low level shortcuts that are implemented in the kernel via the sysrq key which can be used for debugging and recovering from an unresponsive system. Whenever possible, it is recommended that you use these shortcuts instead of doing a hard shutdown (holding down the power button to completely power off the system).<br />
<br />
See [[Wikipedia:Magic SysRq key]] for more details.<br />
<br />
==== Enabling ====<br />
<br />
[[systemd]] has the sysrq permissions bitmask [https://github.com/systemd/systemd/blob/main/sysctl.d/50-default.conf#L14-L19 set to 0x10 by default], which [https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html does not allow process signalling or rebooting], among other things. To allow full use of the sysrq key on your system, add {{ic|1=kernel.sysrq = 1}} to your [[sysctl#Configuration|sysctl configuration]]. Values greater than 1 can be used to selectively enable sysrq functions; see the [https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html Linux kernel documentation] for details. If you want to make sure it will be enabled even before the partitions are mounted and in the initrd, then add {{ic|1=sysrq_always_enabled=1}} to your [[kernel parameters]].<br />
<br />
Note that changing the setting through these methods will cause the changes to persist across reboots. If you want to try changing the sysrq settings for just your current session, you can run either {{ic|1=sysctl kernel.sysrq=1}} or {{ic|echo "1" > /proc/sys/kernel/sysrq}}. <br />
<br />
There are some obvious security risks involved in fully enabling the sysrq key. In addition to forcing reboots and the like, it can be used to dump the contents of the CPU registers, which could theoretically reveal sensitive information. Since using it requires physical access to the system (unless you [https://github.com/jd/sysrqd go out of your way]), most desktop users will probably consider the level of risk acceptable. That said, make sure you fully understand the implications of enabling it and the dynamics of the larger context in which your system is operating before you turn sysrq all the way on.<br />
<br />
==== Rebooting ====<br />
<br />
A common idiom to remember this is "'''R'''eboot '''E'''ven '''I'''f '''S'''ystem '''U'''tterly '''B'''roken" (also referred to as "REISUB"). Alternatively, think of it as "BUSIER" backwards.<br />
<br />
{{Note|Please be aware that "REISUB" itself is just a mnemonic thing, is not any kind of general recommendation of key press sequence to take back control of unresponsive system, you should not blindly press in this sequence each time without knowing their actual function as noted below.}}<br />
<br />
{| class="wikitable"<br />
! Keyboard Shortcut<br />
! Description<br />
|-<br />
| {{ic|Alt+SysRq+r}} Unraw<br />
| Take control of keyboard back from X.<br />
|-<br />
| {{ic|Alt+SysRq+e}} Terminate<br />
| Send SIGTERM to all processes, allowing them to terminate gracefully.<br />
|-<br />
| {{ic|Alt+SysRq+i}} Kill<br />
| Send SIGKILL to all processes, forcing them to terminate immediately.<br />
|-<br />
| {{ic|Alt+SysRq+s}} Sync<br />
| Flush data to disk.<br />
|-<br />
| {{ic|Alt+SysRq+u}} Unmount<br />
| Unmount and remount all filesystems read-only.<br />
|-<br />
| {{ic|Alt+SysRq+b}} Reboot<br />
| Reboot<br />
|-<br />
|}<br />
<br />
==== Killing a memory-hogging process ====<br />
<br />
{{ic|Alt+SysRq+f}} can be used to invoke the [https://www.kernel.org/doc/html/latest/admin-guide/mm/concepts.html?highlight=oom#oom-killer OOM (out-of-memory) killer] without causing a kernel panic if nothing can be killed. The OOM killer uses a set of heuristics to pick whichever relatively non-vital process is using the most memory and kill it. This is very useful to kill a process that is softlocking your system by causing excessive thrashing, such as a runaway browser script, and can alleviate the need for a reboot in many cases. Note that the OOM killer can target a wide variety of processes despite its well-meaning heuristics and can be somewhat unpredictable, so be careful about calling it casually.<br />
<br />
==== Troubleshooting ====<br />
<br />
* If you are using a [[display manager]] and after {{ic|Alt+SysRq+e}} you are presented with the login screen (or full desktop if autologin is enabled), it is most likely caused by {{ic|1=Restart=always}} directive in the relevant [[systemd|service file]]. If necessary, [[edit the unit]], however this should not prevent the "REISUB" sequence from working.<br />
* If all the above combinations work except {{ic|Alt+SysRq+b}}, try using the contralateral {{ic|Alt}} key.<br />
* On laptops that use {{ic|Fn}} key to differentiate {{ic|SysRq}} from {{ic|PrtScrn}}, it may not actually be necessary to use the {{ic|Fn}} key (i.e., {{ic|Alt+PrtSc+''letter''}} could work).<br />
* On Lenovo laptops {{ic|SysRq}} is often configured as {{ic|Fn+S}}. To use it press and hold {{ic|Alt}} then press {{ic|Fn+s}}, '''release''' {{ic|Fn}} and {{ic|s}} still holding {{ic|Alt}} followed by the keys above. <br />
* You may need to press {{ic|Ctrl}} along with {{ic|Alt}}. So for example, full key shortcut would be {{ic|Ctrl+Alt+SysRq+b}}.<br />
<br />
=== Linux console ===<br />
<br />
See [[Linux console#Keyboard shortcuts]].<br />
<br />
=== Xorg and Wayland ===<br />
<br />
{| class="wikitable"<br />
! Keyboard Shortcut<br />
! Description<br />
! Notes<br />
|-<br />
| {{ic|Ctrl+Alt+F1}}, {{ic|F2}}, {{ic|F3}}, ...<br />
| Switch to ''n''-th virtual console<br />
| If it does not work, try {{ic|Ctrl+Alt+Fn+F…}}.<br />
|-<br />
| {{ic|Shift+Insert}} <br> {{ic|Mouse Button 2}}<br />
| Paste text from the [[Clipboard|PRIMARY buffer]]<br />
| By default, Qt maps {{ic|Shift+Insert}} to CLIPBOARD instead of the PRIMARY buffer (see e.g. [https://doc.qt.io/qt-5/qlineedit.html#details]) and {{ic|Ctrl+Shift+Insert}} is mapped to the PRIMARY buffer.<br />
|-<br />
|}<br />
<br />
== Customization ==<br />
<br />
=== Readline ===<br />
<br />
[[Readline]] is a commonly used library for line-editing; it is used for example by [[Bash]], FTP, and many more (see the details of {{Pkg|readline}} package under "Required By" for more examples). It has [[Emacs]]-like and [[vi]]-like editing modes which can be customized with escape sequences. Default key bindings are listed in the [https://tiswww.cwru.edu/php/chet/readline/rluserman.html Info documentation].<br />
<br />
=== Zsh ===<br />
<br />
[[Zsh]] uses [[Zsh#Key_bindings|ZLE]] to link shortcuts to widgets, scripts and commands.<br />
<br />
=== Xorg ===<br />
<br />
See [[Xorg/Keyboard configuration#Frequently used XKB options]] for some common shortcuts, that are disabled by default.<br />
<br />
When we are in a graphical environment we may want to execute a command when certain key combination is pressed (i.e. bind a command to a ''keysym''). There are multiple ways to do that:<br />
<br />
* The most portable way using low level tools, such as [[acpid]]. Not all keys are supported, but configuration in uniform way is possible for keyboard keys, power adapter connection and even headphone jack (un)plugging events. It is also difficult to run programs inside X session correctly.<br />
* The universal way using [[Xorg]] utilities (e.g. [[xbindkeys]]) and eventually your desktop environment or window manager tools.<br />
* The quicker way using a third-party program to do everything in GUI, such as the Gnome Control Center.<br />
<br />
==== sxhkd ====<br />
<br />
A simple X hotkey daemon with a powerful and compact configuration syntax. See [[sxhkd]] for details.<br />
<br />
==== actkbd ====<br />
<br />
From [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/ actkbd home page]:<br />
:{{AUR|actkbd}} (available in [[AUR]]) is a simple daemon that binds actions to keyboard events. It recognises key combinations and can handle press, repeat and release events. Currently it only supports the linux-2.6 evdev interface. It uses a plain-text configuration file which contains all the bindings.<br />
<br />
A sample configuration and guide is available [http://users.softlab.ece.ntua.gr/~thkala/projects/actkbd/latest/README here].<br />
<br />
==== xbindkeys ====<br />
<br />
[[xbindkeys]] allows advanced mapping of keysyms to actions independently of the Desktop Environment.<br />
{{Tip| If you find {{ic|xbindkeys}} difficult to use, try the graphical manager {{AUR|xbindkeys_config-gtk2}} from the [[AUR]].}}<br />
<br />
=== Desktop environments ===<br />
<br />
* [[LXDE#Bindings]]<br />
* [[Xfce#Keyboard Shortcuts]]<br />
<br />
=== Windows managers ===<br />
<br />
* [[Fluxbox#Hotkeys]]<br />
* [[Openbox#Keybinds]]<br />
<br />
=== Key binding for X-selection-paste ===<br />
<br />
{{Accuracy|1={{ic|Shift+Insert}} pastes the PRIMARY buffer.}}<br />
{{Expansion|Why the 100ms delay?}}<br />
<br />
Users who prefer to work with the keyboard rather than the mouse may benefit from a key binding to the paste operation of the middle mouse button. This is especially useful in a keyboard-centered environment. A workflow example is:<br />
<br />
# In Firefox, select a string you want to google for (with the mouse).<br />
# Hit {{ic|Ctrl+k}} to enter the "search engine" field.<br />
# Hit {{ic|F9}} to paste the buffer, instead of moving the mouse pointer to the field and middle-click to paste.<br />
<br />
{{Note|{{ic|Shift+Insert}} has a similar yet different functionality, see [[#Xorg]]: {{ic|Shift+Insert}} inserts the clipboard buffer, not the x-selection-paste buffer. In some applications, these two buffers are mirrored.}}<br />
<br />
The method suggested here uses the following three packages::<br />
<br />
* {{Pkg|xsel}} to give access to the x-selection-buffer content.<br />
* [[Xbindkeys]] to bind a key-stroke to an action.<br />
* {{AUR|xvkbd}} to pass the buffer string to the application by emulating keyboard input.<br />
<br />
This example binds the x-selection-paste operation to the {{ic|F9}} key:<br />
<br />
{{hc|.xbindkeysrc|<br />
"xvkbd -no-jump-pointer -xsendevent -text "\D1`xsel`" 2>/dev/null"<br />
F9<br />
}}<br />
<br />
The {{ic|"\D1"}} code prefixes a 100 ms pause to inserting the selection buffer (see the [http://t-sato.in.coocan.jp/xvkbd/ xvkbd home page]).<br />
<br />
{{Note|Depending on your X configuration, you may need to drop the {{ic|-xsendevent}} argument to xvkbd.}}<br />
The key codes for keys other than {{ic|F9}} can be determined using {{ic|xbindkeys -k}}.<br />
<br />
References:<br />
<br />
* [https://unix.stackexchange.com/questions/11889/pasting-x-selection-not-clipboard-contents-with-keyboard Pasting X selection (not clipboard) contents with keyboard]<br />
* [http://t-sato.in.coocan.jp/xvkbd/ xvkbd home page]<br />
<br />
==== XMonad Window Manager ====<br />
<br />
In the {{Pkg|xmonad}} window manager there is a built-in function to paste the x-selection-buffer content. In order to bind that function to a key-stroke (here {{ic|Insert}} key) the following configuration can be used:<br />
{{hc|xmonad.hs|<br />
import XMonad.Util.Paste<br />
...<br />
-- X-selection-paste buffer<br />
, ((0, xK_Insert), pasteSelection) ]<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
* If you like a keyboard-centered workflow, you might also appreciate a [[Window manager#Tiling_window_managers|tiling window manager]].<br />
<br />
== See also ==<br />
<br />
* [http://lnag.sourceforge.net/lnag_html/node5.html Linux Newbie Administrator Guide - Shortcuts and Commands]<br />
* [https://tldp.org/HOWTO/Keyboard-and-Console-HOWTO.html The Linux keyboard and console HOWTO]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Patching_packages&diff=684534Patching packages2021-06-29T17:26:55Z<p>Thiagowfx: /* Applying patches */ add example with --directory for patch</p>
<hr />
<div>[[Category:Package management]]<br />
[[ja:パッケージにパッチを適用]]<br />
[[pt:Patching packages]]<br />
[[zh-hans:Patching packages]]<br />
{{Related articles start}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
This article covers how to create and how to apply patches to packages in the [[Arch Build System]] (ABS).<br />
<br />
A [[Wikipedia:Patch (computing)|patch]] describes a set of line changes for one or multiple files. Patches are typically used to automate the changing of source code.<br />
<br />
== Creating patches ==<br />
<br />
{{Note|If you only need to change one or two lines, you might want to use [[sed]] instead.}}<br />
<br />
The ''diff'' tool compares files line by line. If you save its output you have got a patch, e.g. {{ic|diff --unified --recursive --text foo bar > patch}}. If you pass directories ''diff'' will compare the files they contain.<br />
<br />
# Delete the {{ic|src}} directory if you have already built the package.<br />
# Run {{ic|makepkg --nobuild}} which will download and extract the source files, specified in {{ic|PKGBUILD}}, but not build them. If the system you are making the patch on does not have the required dependencies, you may have to run {{ic|makepkg --nobuild --nodeps}} instead.<br />
# Create two copies of the extracted directory in the {{ic|src}} directory, one as a pristine copy and one for your altered version. We will call them {{ic|package.orig}} and {{ic|package.new}}.<br />
# Make your changes in the {{ic|package.new}} directory.<br />
# Run {{ic|diff --unified --recursive --text package.orig package.new --color}} and check if the patch looks good.<br />
# Run {{ic|diff --unified --recursive --text package.orig package.new > package.patch}} to create the patch.<br />
# Change into the {{ic|package.orig}} directory and apply the patch using {{ic|1= patch --strip=1 < ../package.patch}}. Verify that the patch is working by building and installing the modified package with {{ic|makepkg --noextract --install}}.<br />
<br />
{{Note|You can also create patches with [[Git]] using {{ic|git diff}} or {{ic|git format-patch}} [https://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit].}}<br />
<br />
See {{man|1|diff}} and {{man|1|git-diff}} for more info.<br />
<br />
== Applying patches ==<br />
<br />
This section outlines how to apply patches you created or downloaded from the Internet from within a {{ic|PKGBUILD}}'s {{ic|prepare()}} function. Follow these steps:<br />
<br />
# Add an entry to the {{ic|source}} array of the {{ic|PKGBUILD}} for the patch file, separated from the original source url by a space. If the file is available online, you can provide the full URL and it will automatically be downloaded and placed in the {{ic|src}} directory. If it is a patch you created yourself, or is otherwise not available, you should place the patch file in the same directory as the {{ic|PKGBUILD}} file, and just add the name of the file to the source array so that it is copied into the {{ic|src}} directory. If you redistribute the {{ic|PKGBUILD}}, you should, of course, include the patch with the {{ic|PKGBUILD}}.<br />
# Then use {{ic|makepkg -g >> PKGBUILD}} or {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}) to update the {{ic|sha512sums}} array. Or manually add an entry to the {{ic|sha512sums}} array; you can generate the sum of your patch using ''sha512sum'' tool.<br />
# Create the {{ic|prepare()}} function in the {{ic|PKGBUILD}} if one is not already present.<br />
# The first step is to change into the directory that needs to be patched (in the {{ic|prepare()}} function, not on your terminal! You want to automate the process of applying the patch). You can do this with something like {{ic|cd "$srcdir/$pkgname-$pkgver"}}. {{ic|$pkgname-$pkgver}} is often the name of a directory created by untarring a downloaded source file, but not in all cases.<br />
# Now you simply need to apply the patch from within this directory. This is very simply done by adding {{ic|1= patch --strip=1 --input=''pkgname''.patch}} to your {{ic|prepare()}} function, changing {{ic|''pkgname''.patch}} to the name of the file containing the diff (the file that was automatically copied into your {{ic|src}} directory because it was in the {{ic|source}} array of the {{ic|PKGBUILD}} file).<br />
<br />
An example prepare-function:<br />
<br />
{{bc|1=<br />
prepare() {<br />
cd "$pkgname-$pkgver"<br />
patch --forward --strip=1 --input="${srcdir}/eject.patch"<br />
}<br />
}}<br />
<br />
Alternatively, you can use the {{ic|--directory}} flag of {{ic|patch}} without having to cd first. The example above would then become:<br />
<br />
{{bc|1=<br />
prepare() {<br />
patch --directory="$pkgname-$pkgver" --forward --strip=1 --input="${srcdir}/eject.patch"<br />
}<br />
}}<br />
<br />
Run {{ic|makepkg}} (from the terminal now). If all goes well, the patch will be automatically applied, and your new package will contain whatever changes were included in the patch. If not, you may have to experiment with the {{ic|--strip}} option of patch. While experimenting, you might find {{ic|--dry-run}}, {{ic|--reverse}} or {{ic|--verbose}} options usable. Read {{man|1|patch}} for more information.<br />
<br />
Basically it works as follows. If the diff file was created to apply patches to files in {{ic|myversion/}}, the diff files will be applied to {{ic|myversion/file}}. You are running it from within the {{ic|yourversion/}} directory (because you would cd into that directory in the {{ic|PKGBUILD}}), so when patch applies the file, you want it to apply it to the file {{ic|file}}, taking off the {{ic|myversion/}} part. {{ic|1= --strip=1}} does this, by removing one directory from the path. However, if the developer patched in {{ic|myfiles/myversion}}, you need to remove two directories, so you use {{ic|1= --strip=2}}.<br />
<br />
If you do not apply a {{ic|--strip}} option, it will take off all directory structure. This is OK if all the files are in the base directory, but if the patch was created on {{ic|myversion/}} and one of the edited files was {{ic|myversion/src/file}}, and you run the patch without a {{ic|--strip}} option from within {{ic|yourversion}}, it will try to patch a file named {{ic|yourversion/file}}.<br />
<br />
Most developers create patches from the parent directory of the directory that is being patched, so {{ic|1= --strip=1}} will usually be right.<br />
<br />
== Using quilt ==<br />
<br />
A simpler way to create patches is using {{Pkg|quilt}} which provides better support for managing many patches, such as applying patches, refreshing patches, and reverting patched files to original state. {{Pkg|quilt}} is used on [[debian:UsingQuilt|Debian]] to manage their patches. See [http://www.shakthimaan.com/downloads/glv/quilt-tutorial/quilt-doc.pdf Using Quilt] for basic information about basic quilt usage to generate, apply patches, and reverting patched files.<br />
<br />
== See also ==<br />
<br />
* http://www.kegel.com/academy/opensource.html — Useful information on patching files</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Patching_packages&diff=684532Patching packages2021-06-29T17:22:36Z<p>Thiagowfx: /* Applying patches */ remove redundant "something similar" repeated twice</p>
<hr />
<div>[[Category:Package management]]<br />
[[ja:パッケージにパッチを適用]]<br />
[[pt:Patching packages]]<br />
[[zh-hans:Patching packages]]<br />
{{Related articles start}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
This article covers how to create and how to apply patches to packages in the [[Arch Build System]] (ABS).<br />
<br />
A [[Wikipedia:Patch (computing)|patch]] describes a set of line changes for one or multiple files. Patches are typically used to automate the changing of source code.<br />
<br />
== Creating patches ==<br />
<br />
{{Note|If you only need to change one or two lines, you might want to use [[sed]] instead.}}<br />
<br />
The ''diff'' tool compares files line by line. If you save its output you have got a patch, e.g. {{ic|diff --unified --recursive --text foo bar > patch}}. If you pass directories ''diff'' will compare the files they contain.<br />
<br />
# Delete the {{ic|src}} directory if you have already built the package.<br />
# Run {{ic|makepkg --nobuild}} which will download and extract the source files, specified in {{ic|PKGBUILD}}, but not build them. If the system you are making the patch on does not have the required dependencies, you may have to run {{ic|makepkg --nobuild --nodeps}} instead.<br />
# Create two copies of the extracted directory in the {{ic|src}} directory, one as a pristine copy and one for your altered version. We will call them {{ic|package.orig}} and {{ic|package.new}}.<br />
# Make your changes in the {{ic|package.new}} directory.<br />
# Run {{ic|diff --unified --recursive --text package.orig package.new --color}} and check if the patch looks good.<br />
# Run {{ic|diff --unified --recursive --text package.orig package.new > package.patch}} to create the patch.<br />
# Change into the {{ic|package.orig}} directory and apply the patch using {{ic|1= patch --strip=1 < ../package.patch}}. Verify that the patch is working by building and installing the modified package with {{ic|makepkg --noextract --install}}.<br />
<br />
{{Note|You can also create patches with [[Git]] using {{ic|git diff}} or {{ic|git format-patch}} [https://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit].}}<br />
<br />
See {{man|1|diff}} and {{man|1|git-diff}} for more info.<br />
<br />
== Applying patches ==<br />
<br />
This section outlines how to apply patches you created or downloaded from the Internet from within a {{ic|PKGBUILD}}'s {{ic|prepare()}} function. Follow these steps:<br />
<br />
# Add an entry to the {{ic|source}} array of the {{ic|PKGBUILD}} for the patch file, separated from the original source url by a space. If the file is available online, you can provide the full URL and it will automatically be downloaded and placed in the {{ic|src}} directory. If it is a patch you created yourself, or is otherwise not available, you should place the patch file in the same directory as the {{ic|PKGBUILD}} file, and just add the name of the file to the source array so that it is copied into the {{ic|src}} directory. If you redistribute the {{ic|PKGBUILD}}, you should, of course, include the patch with the {{ic|PKGBUILD}}.<br />
# Then use {{ic|makepkg -g >> PKGBUILD}} or {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}) to update the {{ic|sha512sums}} array. Or manually add an entry to the {{ic|sha512sums}} array; you can generate the sum of your patch using ''sha512sum'' tool.<br />
# Create the {{ic|prepare()}} function in the {{ic|PKGBUILD}} if one is not already present.<br />
# The first step is to change into the directory that needs to be patched (in the {{ic|prepare()}} function, not on your terminal! You want to automate the process of applying the patch). You can do this with something like {{ic|cd "$srcdir/$pkgname-$pkgver"}}. {{ic|$pkgname-$pkgver}} is often the name of a directory created by untarring a downloaded source file, but not in all cases.<br />
# Now you simply need to apply the patch from within this directory. This is very simply done by adding {{ic|1= patch --strip=1 --input=''pkgname''.patch}} to your {{ic|prepare()}} function, changing {{ic|''pkgname''.patch}} to the name of the file containing the diff (the file that was automatically copied into your {{ic|src}} directory because it was in the {{ic|source}} array of the {{ic|PKGBUILD}} file).<br />
<br />
An example prepare-function:<br />
<br />
{{bc|1=<br />
prepare() {<br />
cd "$pkgname-$pkgver"<br />
patch --forward --strip=1 --input="${srcdir}/eject.patch"<br />
}<br />
}}<br />
<br />
Run {{ic|makepkg}} (from the terminal now). If all goes well, the patch will be automatically applied, and your new package will contain whatever changes were included in the patch. If not, you may have to experiment with the {{ic|--strip}} option of patch. While experimenting, you might find {{ic|--dry-run}}, {{ic|--reverse}} or {{ic|--verbose}} options usable. Read {{man|1|patch}} for more information.<br />
<br />
Basically it works as follows. If the diff file was created to apply patches to files in {{ic|myversion/}}, the diff files will be applied to {{ic|myversion/file}}. You are running it from within the {{ic|yourversion/}} directory (because you would cd into that directory in the {{ic|PKGBUILD}}), so when patch applies the file, you want it to apply it to the file {{ic|file}}, taking off the {{ic|myversion/}} part. {{ic|1= --strip=1}} does this, by removing one directory from the path. However, if the developer patched in {{ic|myfiles/myversion}}, you need to remove two directories, so you use {{ic|1= --strip=2}}.<br />
<br />
If you do not apply a {{ic|--strip}} option, it will take off all directory structure. This is ok if all the files are in the base directory, but if the patch was created on {{ic|myversion/}} and one of the edited files was {{ic|myversion/src/file}}, and you run the patch without a {{ic|--strip}} option from within {{ic|yourversion}}, it will try to patch a file named {{ic|yourversion/file}}.<br />
<br />
Most developers create patches from the parent directory of the directory that is being patched, so {{ic|1= --strip=1}} will usually be right.<br />
<br />
== Using quilt ==<br />
<br />
A simpler way to create patches is using {{Pkg|quilt}} which provides better support for managing many patches, such as applying patches, refreshing patches, and reverting patched files to original state. {{Pkg|quilt}} is used on [[debian:UsingQuilt|Debian]] to manage their patches. See [http://www.shakthimaan.com/downloads/glv/quilt-tutorial/quilt-doc.pdf Using Quilt] for basic information about basic quilt usage to generate, apply patches, and reverting patched files.<br />
<br />
== See also ==<br />
<br />
* http://www.kegel.com/academy/opensource.html — Useful information on patching files</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Rss2email&diff=684310Rss2email2021-06-29T04:10:45Z<p>Thiagowfx: add related articles section, linking to RSS</p>
<hr />
<div>{{Lowercase title}}<br />
{{Related articles start}}<br />
{{Related|Web feed}}<br />
{{Related articles end}}<br />
[[Category:News aggregators]]<br />
[[Category:Email]]<br />
[[ja:Rss2email]]<br />
[https://github.com/rss2email/rss2email rss2email] is a free tool for retrieving content from RSS feeds and mailing it. It is useful for those who do not want yet another program with which to keep up and for people who have a system for e-mail management that they would like to apply to their RSS feeds as well. People with lots of e-mail often have highly customized systems that let them process their mail efficiently; rss2email allows them to easily apply this system to their feeds as well.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{AUR|rss2email}} package.<br />
<br />
== Adding feeds ==<br />
<br />
First, tell ''rss2email'' where it should send feeds by running the command:<br />
<br />
$ r2e new ''user@example.com''<br />
<br />
Next, subscribe to an RSS feed. For example, to subscribe to the Arch Linux package updates feed, run:<br />
<br />
$ r2e add ''name-for-rss'' <nowiki>https://www.archlinux.org/feeds/packages/</nowiki> ''e-mail address''<br />
<br />
Note that an e-mail address only has to be given if the feed is to be delivered to an address other than the default one; otherwise, leaving off the e-mail address is acceptable.<br />
<br />
After a new feed is added, ''rss2email'' will e-mail every post it has not previously e-mailed. The first time it is run, therefore, it will e-mail every post. To avoid this behavior, after adding a new feed, run:<br />
<br />
$ r2e run --no-send<br />
<br />
== Getting RSS feeds ==<br />
<br />
To get new stories, execute the command:<br />
<br />
$ r2e run<br />
<br />
To automate this process and have ''rss2email'' check for new feeds every 30 minutes, see [[Autostarting#On time events]].<br />
<br />
== Managing rss2email ==<br />
<br />
{{Expansion|Need to add permission info.}}<br />
<br />
To view feeds previously added to rss2email, run:<br />
<br />
r2e list<br />
<br />
This will output a numbered list of feeds. To delete a feed, run:<br />
<br />
r2e delete ''number''<br />
<br />
where ''number'' is the number of the feed to be deleted.<br />
<br />
To change the default e-mail address, run:<br />
<br />
r2e email ''new_address@example.net''<br />
<br />
== Advanced configuration ==<br />
<br />
The following configuration changes should be made in {{ic|rss2email.cfg}}, which should be located at {{ic|~/.config/rss2email.cfg}}.<br />
<br />
To have RSS entries sent as HTML e-mails instead of as plain text, set:<br />
<br />
HTML-MAIL = 1<br />
<br />
To receive new e-mails when RSS posts are updated, set:<br />
<br />
TRUST-GUID = 0<br />
<br />
To set the date header of e-mails to when the RSS post was written, rather than when the e-mail is actually sent, set:<br />
<br />
DATE-HEADER = 1<br />
<br />
To fix the error message "sender domain must exist" or to change the address from which e-mails are sent, set:<br />
<br />
FROM = user@example.com<br />
<br />
To force all feeds to use this address, even if they have their own address set, use:<br />
<br />
FORCE-FROM = 1<br />
<br />
To have rss2email automatically wrap long lines, set:<br />
<br />
BODY-WIDTH = 72<br />
<br />
Where 72 is the number of characters after which rss2email should start a new line.<br />
<br />
To send mail using an SMTP server rather than the local machine, use:<br />
<br />
SMTP_SEND = 1<br />
SMTP_SERVER = ''smtp.example.com:25''<br />
<br />
If the SMTP server requires authentication, set:<br />
<br />
SMTP-AUTH = 1<br />
SMTP-USERNAME = ''user@example.com''<br />
SMTP-PASSSWORD = ''password''<br />
<br />
== See also ==<br />
<br />
* https://web.archive.org/web/20100412191758/http://www.allthingsrss.com/rss2email/?page_id=31#unix - Official getting started page<br />
* https://www.linux.com/archive/feed/50469 - linux.com article.</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Pacman/Pacnew_and_Pacsave&diff=682364Pacman/Pacnew and Pacsave2021-06-20T03:20:31Z<p>Thiagowfx: /* Third-party utilities */ fix template usage</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[cs:Pacman (Čeština)/Pacnew and Pacsave]]<br />
[[de:Pacnew- und Pacsave-Dateien]]<br />
[[es:Pacman (Español)/Pacnew and Pacsave]]<br />
[[fr:Pacman (Français)/Pacnew and Pacsave]]<br />
[[it:Pacman (Italiano)/Pacnew and Pacsave]]<br />
[[ja:Pacnew と Pacsave ファイル]]<br />
[[pt:Pacman (Português)/Pacnew and Pacsave]]<br />
[[ru:Pacman (Русский)/Pacnew and Pacsave]]<br />
[[zh-hans:Pacman (简体中文)/Pacnew and Pacsave]]<br />
When ''pacman'' removes a package that has a configuration file, it normally creates a backup copy of that config file and appends ''.pacsave'' to the name of the file. Likewise, when ''pacman'' upgrades a package which includes a new config file created by the maintainer differing from the currently installed file, it saves a ''.pacnew'' file with the new configuration. ''pacman'' provides notice when these files are written.<br />
<br />
== Why these files are created ==<br />
<br />
A ''.pacnew'' file may be created during a package upgrade ({{ic|pacman -Syu}}, {{ic|pacman -Su}} or {{ic|pacman -U}}) to avoid overwriting a file which already exists and was previously modified by the user. When this happens, a message like the following will appear in the output of ''pacman'':<br />
<br />
warning: /etc/pam.d/usermod installed as /etc/pam.d/usermod.pacnew<br />
<br />
A ''.pacsave'' file may be created during a package removal ({{ic|pacman -R}}), or by a package upgrade (the package must be removed first). When the pacman database has a record that a certain file owned by the package should be backed up, it will create a ''.pacsave'' file. When this happens pacman outputs a message like the following:<br />
<br />
warning: /etc/pam.d/usermod saved as /etc/pam.d/usermod.pacsave<br />
<br />
These files require manual intervention from the user and it is good practice to handle them right after every package upgrade or removal. If left unhandled, improper configurations can result in improper function of the software or the software being unable to run altogether.<br />
<br />
== Package backup files ==<br />
<br />
A package's [[PKGBUILD]] file specifies which files should be preserved or backed up when the package is upgraded or removed. For example, the PKGBUILD for {{pkg|pulseaudio}} contains the following line:<br />
<br />
backup=(etc/pulse/{daemon.conf,default.pa,system.pa})<br />
<br />
After installation, this list can be queried from the pacman database using {{ic|pacman -Qii ''package_name''}}.<br />
<br />
To prevent any package from overwriting a certain file, see [[Pacman#Skip file from being upgraded]].<br />
<br />
== Types explained ==<br />
<br />
=== .pacnew ===<br />
<br />
For each of the [[#Package backup files]] being upgraded, pacman cross-compares three [[wikipedia:Md5sum|md5sums]] generated from the file's contents: one sum for the version originally installed by the package, one for the version currently in the filesystem, and one for the version in the new package. If the version of the file currently in the filesystem has been modified from the version originally installed by the package, pacman cannot know how to merge those changes with the new version of the file. Therefore, instead of overwriting the modified file when upgrading, pacman saves the new version with a ''.pacnew'' extension and leaves the modified version untouched.<br />
<br />
Going into further detail, the 3-way MD5 sum comparison results in one of the following outcomes:<br />
<br />
; original = ''X'', current = ''X'', new = ''X'' : All three versions of the file have identical contents, so overwriting is not a problem. Overwrite the current version with the new version and do not notify the user (although the file contents are the same, this overwrite will update the filesystem's information regarding the file's installed, modified, and accessed times, as well as ensure that any file permission changes are applied).<br />
<br />
; original = ''X'', current = ''X'', new = ''Y'' : The current version's contents are identical to the original's, but the new version is different. Since the user has not modified the current version and the new version may contain improvements or bugfixes, overwrite the current version with the new version and do not notify the user. This is the only auto-merging of new changes that pacman is capable of performing.<br />
<br />
; original = ''X'', current = ''Y'', new = ''X'' : The original package and the new package both contain exactly the same version of the file, but the version currently in the filesystem has been modified. Leave the current version in place and discard the new version without notifying the user.<br />
<br />
; original = ''X'', current = ''Y'', new = ''Y'' : The new version is identical to the current version. Overwrite the current version with the new version and do not notify the user (although the file contents are the same, this overwrite will update the filesystem's information regarding the file's installed, modified, and accessed times, as well as ensure that any file permission changes are applied).<br />
<br />
; original = ''X'', current = ''Y'', new = ''Z'' : All three versions are different, so leave the current version in place, install the new version with a ''.pacnew'' extension and warn the user about the new version. The user will be expected to manually merge any changes necessary from the new version into the current version.<br />
<br />
Rarely, when an upgraded package includes a backup file the previous version did not, the situation is correctly handled as X/Y/Y or X/Y/Z, with X being a non-existant value.<br />
<br />
=== .pacsave ===<br />
<br />
If the user has modified one of the files specified in {{ic|backup}} then that file will be renamed with a ''.pacsave'' extension and will remain in the filesystem after the rest of the package is removed.<br />
<br />
{{Note| Use of the {{ic|-n}} option with {{ic|pacman -R}} will result in complete removal of ''all'' files in the specified package, therefore no ''.pacsave'' files will be created.}}<br />
<br />
== Locating .pac* files ==<br />
<br />
Pacman does not deal with ''.pacnew'' files automatically: you must maintain these yourself. A few tools are presented in the next section. To do this manually, you will first need to locate them. When upgrading or removing a large number of packages, updated ''.pac*'' files may be missed. To discover whether any ''.pac*'' files have been installed, use one of the following:<br />
<br />
* To search within {{ic|/etc}} where most global configurations are stored: {{bc|$ find /etc -regextype posix-extended -regex ".+\.pac(new{{!}}save)" 2> /dev/null}} or to search within the entire disk replacing {{ic|/etc}} by {{ic|/}} in the command above (in which case you may want to [https://stackoverflow.com/a/4210072 selectively skip certain directories] to speed up the search).<br />
* If installed, [[locate]] can also be used. First re-index the database: {{bc|# updatedb}} Then run: {{bc|$ locate --existing --regex "\.pac(new{{!}}save)$"}}<br />
* Use pacman's log to find them: {{bc|$ grep --extended-regexp "\.pac(new{{!}}save)" /var/log/pacman.log}} Note that the log does not keep track of the files currently in the filesystem nor the ones that have already been removed; the above command will list all ''.pac*'' files that have ever existed on your system. In order to only get the 10 most recent ''.pac*'' files, pipe the result to {{ic|tail}}.<br />
<br />
== Managing .pac* files ==<br />
<br />
=== pacdiff ===<br />
<br />
{{pkg|pacman-contrib}} provides the simple ''pacdiff'' tool for managing ''.pac*'' files. It will search all ''.pacnew'' and ''.pacsave'' files and ask for any actions on them. It uses [[Vim#Merging files|vimdiff]] by default, but you may specify a different tool with {{ic|1=DIFFPROG=''your_editor'' pacdiff}}. See [[List of applications/Utilities#Comparison, diff, merge]] for other common comparison tools.<br />
<br />
=== Third-party utilities ===<br />
<br />
A few third-party utilities providing various levels of automation for these tasks are available from the [[AUR]].<br />
<br />
You can use one of the following tools:<br />
<br />
*{{App|dotpac|Basic interactive script with ncurses-based text interface and helpful walkthrough. No merging or auto-merging features.|https://github.com/AladW/dotpac|{{AUR|dotpac}}}}<br />
*{{App|etc-update|''Gentoo''<nowiki>'</nowiki>s utility, compatible with other distributions including Arch. It provides a simple CLI to view, merge and interactively edit changes. Trivial changes, such as comments, can be merged automatically.|https://wiki.gentoo.org/wiki/Handbook:Parts/Portage/Tools#etc-update|{{AUR|etc-update}}}}<br />
*{{App|p3wm|Three-way merge ''.pacnew'' files. It can automatically merge trivial changes. If conflicts happen, it will launch vimdiff, meld or kdiff3 to resolve them.|https://github.com/5long/p3wm|{{AUR|p3wm}}}}<br />
*{{App|pacnews-git|A simple script aimed at finding all ''.pacnew'' files, then editing them with [[Vim#Merging files|vimdiff]].|https://github.com/pbrisbin/scripts/blob/master/pacnews|{{AUR|pacnews-git}}}}<br />
*{{App|pacfiles-mode|A package for [[Emacs]] to manage and merge ''.pacnew'' files, available in [https://melpa.org/#/pacfiles-mode melpa].|https://github.com/UndeadKernel/pacfiles-mode}}<br />
*{{App|pacdiff-pacman-hook-git|Pacman hook to run pacdiff automatically|https://github.com/desbma/pacman-hooks|{{AUR|pacdiff-pacman-hook-git}}}}<br />
<br />
== See also ==<br />
<br />
* Forum thread: [https://bbs.archlinux.org/viewtopic.php?id=53532 Dealing with .pacnew files]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Pacman/Pacnew_and_Pacsave&diff=682363Pacman/Pacnew and Pacsave2021-06-20T03:18:46Z<p>Thiagowfx: /* Third-party utilities */ add https://aur.archlinux.org/packages/pacdiff-pacman-hook-git</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[cs:Pacman (Čeština)/Pacnew and Pacsave]]<br />
[[de:Pacnew- und Pacsave-Dateien]]<br />
[[es:Pacman (Español)/Pacnew and Pacsave]]<br />
[[fr:Pacman (Français)/Pacnew and Pacsave]]<br />
[[it:Pacman (Italiano)/Pacnew and Pacsave]]<br />
[[ja:Pacnew と Pacsave ファイル]]<br />
[[pt:Pacman (Português)/Pacnew and Pacsave]]<br />
[[ru:Pacman (Русский)/Pacnew and Pacsave]]<br />
[[zh-hans:Pacman (简体中文)/Pacnew and Pacsave]]<br />
When ''pacman'' removes a package that has a configuration file, it normally creates a backup copy of that config file and appends ''.pacsave'' to the name of the file. Likewise, when ''pacman'' upgrades a package which includes a new config file created by the maintainer differing from the currently installed file, it saves a ''.pacnew'' file with the new configuration. ''pacman'' provides notice when these files are written.<br />
<br />
== Why these files are created ==<br />
<br />
A ''.pacnew'' file may be created during a package upgrade ({{ic|pacman -Syu}}, {{ic|pacman -Su}} or {{ic|pacman -U}}) to avoid overwriting a file which already exists and was previously modified by the user. When this happens, a message like the following will appear in the output of ''pacman'':<br />
<br />
warning: /etc/pam.d/usermod installed as /etc/pam.d/usermod.pacnew<br />
<br />
A ''.pacsave'' file may be created during a package removal ({{ic|pacman -R}}), or by a package upgrade (the package must be removed first). When the pacman database has a record that a certain file owned by the package should be backed up, it will create a ''.pacsave'' file. When this happens pacman outputs a message like the following:<br />
<br />
warning: /etc/pam.d/usermod saved as /etc/pam.d/usermod.pacsave<br />
<br />
These files require manual intervention from the user and it is good practice to handle them right after every package upgrade or removal. If left unhandled, improper configurations can result in improper function of the software or the software being unable to run altogether.<br />
<br />
== Package backup files ==<br />
<br />
A package's [[PKGBUILD]] file specifies which files should be preserved or backed up when the package is upgraded or removed. For example, the PKGBUILD for {{pkg|pulseaudio}} contains the following line:<br />
<br />
backup=(etc/pulse/{daemon.conf,default.pa,system.pa})<br />
<br />
After installation, this list can be queried from the pacman database using {{ic|pacman -Qii ''package_name''}}.<br />
<br />
To prevent any package from overwriting a certain file, see [[Pacman#Skip file from being upgraded]].<br />
<br />
== Types explained ==<br />
<br />
=== .pacnew ===<br />
<br />
For each of the [[#Package backup files]] being upgraded, pacman cross-compares three [[wikipedia:Md5sum|md5sums]] generated from the file's contents: one sum for the version originally installed by the package, one for the version currently in the filesystem, and one for the version in the new package. If the version of the file currently in the filesystem has been modified from the version originally installed by the package, pacman cannot know how to merge those changes with the new version of the file. Therefore, instead of overwriting the modified file when upgrading, pacman saves the new version with a ''.pacnew'' extension and leaves the modified version untouched.<br />
<br />
Going into further detail, the 3-way MD5 sum comparison results in one of the following outcomes:<br />
<br />
; original = ''X'', current = ''X'', new = ''X'' : All three versions of the file have identical contents, so overwriting is not a problem. Overwrite the current version with the new version and do not notify the user (although the file contents are the same, this overwrite will update the filesystem's information regarding the file's installed, modified, and accessed times, as well as ensure that any file permission changes are applied).<br />
<br />
; original = ''X'', current = ''X'', new = ''Y'' : The current version's contents are identical to the original's, but the new version is different. Since the user has not modified the current version and the new version may contain improvements or bugfixes, overwrite the current version with the new version and do not notify the user. This is the only auto-merging of new changes that pacman is capable of performing.<br />
<br />
; original = ''X'', current = ''Y'', new = ''X'' : The original package and the new package both contain exactly the same version of the file, but the version currently in the filesystem has been modified. Leave the current version in place and discard the new version without notifying the user.<br />
<br />
; original = ''X'', current = ''Y'', new = ''Y'' : The new version is identical to the current version. Overwrite the current version with the new version and do not notify the user (although the file contents are the same, this overwrite will update the filesystem's information regarding the file's installed, modified, and accessed times, as well as ensure that any file permission changes are applied).<br />
<br />
; original = ''X'', current = ''Y'', new = ''Z'' : All three versions are different, so leave the current version in place, install the new version with a ''.pacnew'' extension and warn the user about the new version. The user will be expected to manually merge any changes necessary from the new version into the current version.<br />
<br />
Rarely, when an upgraded package includes a backup file the previous version did not, the situation is correctly handled as X/Y/Y or X/Y/Z, with X being a non-existant value.<br />
<br />
=== .pacsave ===<br />
<br />
If the user has modified one of the files specified in {{ic|backup}} then that file will be renamed with a ''.pacsave'' extension and will remain in the filesystem after the rest of the package is removed.<br />
<br />
{{Note| Use of the {{ic|-n}} option with {{ic|pacman -R}} will result in complete removal of ''all'' files in the specified package, therefore no ''.pacsave'' files will be created.}}<br />
<br />
== Locating .pac* files ==<br />
<br />
Pacman does not deal with ''.pacnew'' files automatically: you must maintain these yourself. A few tools are presented in the next section. To do this manually, you will first need to locate them. When upgrading or removing a large number of packages, updated ''.pac*'' files may be missed. To discover whether any ''.pac*'' files have been installed, use one of the following:<br />
<br />
* To search within {{ic|/etc}} where most global configurations are stored: {{bc|$ find /etc -regextype posix-extended -regex ".+\.pac(new{{!}}save)" 2> /dev/null}} or to search within the entire disk replacing {{ic|/etc}} by {{ic|/}} in the command above (in which case you may want to [https://stackoverflow.com/a/4210072 selectively skip certain directories] to speed up the search).<br />
* If installed, [[locate]] can also be used. First re-index the database: {{bc|# updatedb}} Then run: {{bc|$ locate --existing --regex "\.pac(new{{!}}save)$"}}<br />
* Use pacman's log to find them: {{bc|$ grep --extended-regexp "\.pac(new{{!}}save)" /var/log/pacman.log}} Note that the log does not keep track of the files currently in the filesystem nor the ones that have already been removed; the above command will list all ''.pac*'' files that have ever existed on your system. In order to only get the 10 most recent ''.pac*'' files, pipe the result to {{ic|tail}}.<br />
<br />
== Managing .pac* files ==<br />
<br />
=== pacdiff ===<br />
<br />
{{pkg|pacman-contrib}} provides the simple ''pacdiff'' tool for managing ''.pac*'' files. It will search all ''.pacnew'' and ''.pacsave'' files and ask for any actions on them. It uses [[Vim#Merging files|vimdiff]] by default, but you may specify a different tool with {{ic|1=DIFFPROG=''your_editor'' pacdiff}}. See [[List of applications/Utilities#Comparison, diff, merge]] for other common comparison tools.<br />
<br />
=== Third-party utilities ===<br />
<br />
A few third-party utilities providing various levels of automation for these tasks are available from the [[AUR]].<br />
<br />
You can use one of the following tools:<br />
<br />
*{{App|dotpac|Basic interactive script with ncurses-based text interface and helpful walkthrough. No merging or auto-merging features.|https://github.com/AladW/dotpac|{{AUR|dotpac}}}}<br />
*{{App|etc-update|''Gentoo''<nowiki>'</nowiki>s utility, compatible with other distributions including Arch. It provides a simple CLI to view, merge and interactively edit changes. Trivial changes, such as comments, can be merged automatically.|https://wiki.gentoo.org/wiki/Handbook:Parts/Portage/Tools#etc-update|{{AUR|etc-update}}}}<br />
*{{App|p3wm|Three-way merge ''.pacnew'' files. It can automatically merge trivial changes. If conflicts happen, it will launch vimdiff, meld or kdiff3 to resolve them.|https://github.com/5long/p3wm|{{AUR|p3wm}}}}<br />
*{{App|pacnews-git|A simple script aimed at finding all ''.pacnew'' files, then editing them with [[Vim#Merging files|vimdiff]].|https://github.com/pbrisbin/scripts/blob/master/pacnews|{{AUR|pacnews-git}}}}<br />
*{{App|pacfiles-mode|A package for [[Emacs]] to manage and merge ''.pacnew'' files, available in [https://melpa.org/#/pacfiles-mode melpa].|https://github.com/UndeadKernel/pacfiles-mode}}<br />
*{{App|pacdiff-pacman-hook-git|Pacman hook to run pacdiff automatically|{{AUR|pacdiff-pacman-hook-git}}}}<br />
<br />
== See also ==<br />
<br />
* Forum thread: [https://bbs.archlinux.org/viewtopic.php?id=53532 Dealing with .pacnew files]</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Flyspray&diff=682359Flyspray2021-06-20T02:48:50Z<p>Thiagowfx: linkify URL</p>
<hr />
<div>[[Category:Issue tracking systems]]<br />
[[es:Flyspray]]<br />
[[ja:Flyspray]]<br />
[[pt:Flyspray]]<br />
[[zh-hans:Flyspray]]<br />
{{Related articles start}}<br />
{{Related|LAMP}}<br />
{{Related articles end}}<br />
<br />
[https://www.flyspray.org/ Flyspray] is a bug tracking system written in [[PHP]]. FlySpray is notably used by Arch Linux itself (https://bugs.archlinux.org).<br />
<br />
== Status in Arch Linux ==<br />
<br />
Issue {{Bug|24999}} was in progress to migrate away from FlySpray to Bugzilla. Unfortunately the main developer abandoned the project due to lack of time/interest.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|flyspray}} package. Flyspray requires a web server such as [[Apache HTTP Server]] with [[PHP]], and an SQL server such as [[MySQL]] or [[PostgreSQL]].<br />
<br />
=== Apache Setup ===<br />
<br />
{{note|You will need to have [[Apache HTTP Server]] configured to run with [[PHP]]. Check [[Apache HTTP Server#PHP]] for instructions. Make sure to uncomment {{ic|1=extension=mysqli}} in {{ic|/etc/php/php.ini}}.}}<br />
<br />
You will need to create a config file for apache to find your Flyspray install. Create the following file:<br />
<br />
{{hc|/etc/httpd/conf/extra/flyspray.conf|<br />
Alias /flyspray "/usr/share/webapps/flyspray"<br />
<Directory "/usr/share/webapps/flyspray"><br />
AllowOverride All<br />
Options FollowSymlinks<br />
Require all granted<br />
php_admin_value open_basedir "/srv/http/:/tmp/:/usr/share/webapps/flyspray"<br />
</Directory>}}<br />
<br />
You will then need to edit {{ic|/etc/webapps/flyspray/.htaccess}} and change {{ic|deny from all}} to {{ic|allow from all}}. You should now be able to navigate to the flyspray interface (e.g. http://localhost/flyspray) and it will show a page of pre-installation checks. Any issues here should be resolved before continuing.</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Fish&diff=678385Fish2021-06-09T19:54:00Z<p>Thiagowfx: /* Command completion */ delete cower reference</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Command-line shells]]<br />
[[de:Fish]]<br />
[[ja:Fish]]<br />
[[ru:Fish]]<br />
[[zh-hans:Fish]]<br />
{{Related articles start}}<br />
{{Related|Command-line shell}}<br />
{{Related articles end}}<br />
<br />
[https://fishshell.com fish], the '''''f'''riendly '''i'''nteractive '''sh'''ell'', is a [[command-line shell|commandline shell]] intended to be interactive and user-friendly.<br />
<br />
''fish'' is intentionally not fully [[Wikipedia:POSIX|POSIX]] compliant, it aims at addressing POSIX inconsistencies (as perceived by the creators) with a simplified or a different syntax. This means that even simple POSIX compliant scripts may require some significant adaptation or even full rewriting to run with fish.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|fish}} package. For the development version, install the {{AUR|fish-git}} package.<br />
<br />
Once installed, simply type {{ic|fish}} to drop into the fish shell.<br />
<br />
Documentation can be found by typing {{ic|help}} from fish; it will be opened in a web browser. It is recommended to read at least the "Syntax overview" section, since fish's syntax is different from many other shells.<br />
<br />
== System integration ==<br />
<br />
One must decide whether fish is going to be the default user's shell, which means that the user falls directly in fish at login, or whether it is used in interactive terminal mode as a child process of the current default shell, here we will assume the latter is [[Bash]]. To elaborate on these two setups:<br />
<br />
* fish used as the '''default shell''': this mode requires some basic understanding of the fish functioning and its scripting language. The user's current initialization scripts and environment variables need to be migrated to the new fish environment. To configure the system in this mode, follow [[#Setting fish as default shell]].<br />
<br />
* fish used as an '''interactive shell only''': this is the less disruptive mode, all the Bash initialization scripts are run as usual and fish runs on top of Bash in interactive mode connected to a terminal. To setup fish in this mode, follow [[#Setting fish as interactive shell only]].<br />
<br />
=== Setting fish as default shell ===<br />
<br />
If you decide to set fish as the default user shell, the first step is to set the shell of this particular user to {{ic|/usr/bin/fish}}. This can be done by following the instructions in [[Command-line shell#Changing your default shell]].<br />
<br />
The next step is to port the current needed actions and configuration performed in the various Bash initialization scripts, namely {{ic|/etc/profile}}, {{ic|~/.bash_profile}}, {{ic|/etc/bash.bashrc}} and {{ic|~/.bashrc}}, into the fish framework.<br />
<br />
In particular, the content of the {{ic|$PATH}} environment variable, once directly logged under fish, should be checked and adjusted to one's need. In fish, {{ic|$PATH}} is defined as a ''global environment variable'': it has a ''global'' scope across all functions, it is lost upon reboot and it is an ''environment variable'' which means it is exported to child processes.<br />
The recommended way of adding additional locations to the path is by calling the [https://fishshell.com/docs/current/cmds/fish_add_path.html fish_add_path] command from {{ic|config.fish}}. For example:<br />
<br />
$ fish_add_path -p ''/first/path'' ''/second/path'' ''/third/one''<br />
<br />
These three locations will be prepended to the path.<br />
<br />
=== Setting fish as interactive shell only ===<br />
<br />
Not setting fish as system wide or user default allows the current Bash scripts to run on startup. It ensures the current user's environment variables are unchanged and are exported to fish which then runs as a Bash child. Below are several ways of running fish in interactive mode without setting it as the default shell.<br />
<br />
==== Modify .bashrc to drop into fish ====<br />
<br />
{{Accuracy|1=Using {{ic|exec fish}} in {{ic|.bashrc}} may not actually be a great idea, see e.g. https://bugzilla.redhat.com/show_bug.cgi?id=1910424.}}<br />
<br />
Keep the default shell as Bash and simply add the line {{ic|exec fish}} to the appropriate [[Bash#Configuration files]], such as {{ic|.bashrc}}. This will allow Bash to properly source {{ic|/etc/profile}} and all files in {{ic|/etc/profile.d}}. Because fish replaces the Bash process, exiting fish will also exit the terminal. Compared to the following options, this is the most universal solution, since it works both on a local machine and on a SSH server.<br />
<br />
{{Tip|<br />
* In this setup, use {{ic|bash --norc}} to manually enter Bash without executing the commands from {{ic|~/.bashrc}} which would run {{ic|exec fish}} and drop back into fish.<br />
* To have commands such as {{ic|bash -c 'echo test'}} run the command in Bash instead of starting fish, you can write {{ic|if [ -z "$BASH_EXECUTION_STRING" ]; then exec fish; fi}} instead.<br />
* Drop in to fish only if the parent process is not fish. This allows to quickly enter in to bash by invoking {{ic|bash}} command without losing {{ic|~/.bashrc}} configuration: {{bc|<nowiki>if [[ $(ps --no-header --pid=$PPID --format=cmd) != "fish" ]]<br />
then<br />
exec fish<br />
fi</nowiki>}}}}<br />
<br />
==== Use terminal emulator options ====<br />
<br />
Another option is to open your terminal emulator with a command line option that executes fish. For most terminals this is the {{ic|-e}} switch, so for example, to open gnome-terminal using fish, change your shortcut to use:<br />
<br />
gnome-terminal -e fish<br />
<br />
With terminal emulators that do not support setting the shell, for example {{aur|lilyterm-git}}, it would look like this:<br />
<br />
SHELL=/usr/bin/fish lilyterm<br />
<br />
Also, depending on the terminal, you may be able to set fish as the default shell in either the terminal configuration or the terminal profile.<br />
<br />
==== Use terminal multiplexer options ====<br />
<br />
To set fish as the shell started in [[tmux]], put this into your {{ic|~/.tmux.conf}}:<br />
<br />
set-option -g default-shell "/usr/bin/fish"<br />
<br />
Whenever you run ''tmux'', you will be dropped into fish.<br />
<br />
== Configuration ==<br />
<br />
The configuration file runs at every login and is located at {{ic|~/.config/fish/config.fish}}. Adding commands or functions to the file will execute/define them when opening a terminal, similar to {{ic|.bashrc}}. Note that whenever a variable needs to be preserved, it should be set as ''universal'' rather than defined in the aforementioned configuration file.<br />
<br />
The user's functions are located in the directory {{ic|~/.config/fish/functions}} under the filenames {{ic|''function_name''.fish}}.<br />
<br />
=== Web interface ===<br />
<br />
The fish terminal colors, prompt, functions, variables, history, bindings and abbreviations can be set with the interactive web interface:<br />
<br />
fish_config<br />
<br />
It may fail to start if IPv6 has been disabled. See [https://github.com/fish-shell/fish-shell/issues/3857#issuecomment-281631629] and [[IPv6#Disable IPv6]].<br />
<br />
=== Command completion ===<br />
<br />
fish can generate autocompletions from man pages. Completions are written to {{ic|~/.local/share/fish/generated_completions/}} and can be generated by calling:<br />
<br />
fish_update_completions<br />
<br />
You can also define your own completions in {{ic|~/.config/fish/completions/}}. See {{ic|/usr/share/fish/completions/}} for a few examples.<br />
<br />
Context-aware completions for Arch Linux-specific commands like ''pacman'', ''pacman-key'', ''makepkg'', ''pbget'', ''pacmatic'' are built into fish, since the policy of the fish development is to include all the existent completions in the upstream tarball. The memory management is clever enough to avoid any negative impact on resources.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Command substitution ===<br />
<br />
''fish'' does not implement Bash style history substitution (e.g. {{ic|sudo !!}}), and the developers recommend in the [https://fishshell.com/docs/current/faq.html#why-doesn-t-history-substitution-etc-work fish faq] to use the interactive history recall interface instead: the {{ic|Up}} arrow recalls whole past lines and {{ic|Alt+Up}} (or {{ic|Alt+.}}) recalls individual arguments, while {{ic|Alt+s}} prepends {{ic|sudo}} to the existing line.<br />
<br />
However some workarounds are described in the [https://github.com/fish-shell/fish-shell/wiki/Bash-Style-Command-Substitution-and-Chaining-(!!-!$-&&-%7C%7C) fish wiki]: while not providing complete history substitution, some functions replace {{ic|!!}} with the previous command or {{ic|!$}} with the previous last argument.<br />
<br />
=== Command chaining ===<br />
<br />
Command chaining {{ic|&&}} and {{ic|{{!}}{{!}}}} is not implemented in versions older than 3.0 and the recommended syntax to achieve similar results in ''fish'' is respectively {{ic|; and}} and {{ic|; or}}.<br />
Some keybindings can be set for automatic substitution as described in the [https://github.com/fish-shell/fish-shell/wiki/Bash-Style-Command-Substitution-and-Chaining-(!!-!$-&&-%7C%7C)#getting--and- fish wiki].<br />
<br />
=== Disable greeting ===<br />
<br />
By default, fish prints a greeting message at startup. To disable it, run once:<br />
<br />
$ set -U fish_greeting<br />
<br />
This clears the universal {{ic|fish_greeting}} variable, shared with all fish instances and which is preserved upon restart of the shell.<br />
<br />
=== Make su launch fish ===<br />
<br />
If ''su'' starts with Bash because Bash is the target user's (''root'' if no username is provided) default shell, one can define a function to redirect it to fish whatever the user's shell:<br />
{{hc|~/.config/fish/functions/su.fish|2=<br />
function su<br />
command su --shell=/usr/bin/fish $argv<br />
end}}<br />
<br />
=== Start X at login ===<br />
<br />
Add the following to the bottom of your {{ic|~/.config/fish/config.fish}}.<br />
<br />
{{bc|1=<nowiki><br />
# Start X at login<br />
if status is-login<br />
if test -z "$DISPLAY" -a "$XDG_VTNR" = 1<br />
exec startx -- -keeptty<br />
end<br />
end<br />
</nowiki>}}<br />
<br />
For those running fish in interactive mode, replace {{ic|status is-login}} with {{ic|status is-interactive}} in the above code.<br />
<br />
=== Put git status in prompt ===<br />
<br />
If you would like fish to display the branch and dirty status when you are in a git directory, you can define the following {{ic|fish_prompt}} function:<br />
{{hc|~/.config/fish/functions/fish_prompt.fish|<br />
<nowiki>function fish_prompt<br />
set -l last_status $status<br />
<br />
if not set -q __fish_git_prompt_show_informative_status<br />
set -g __fish_git_prompt_show_informative_status 1<br />
end<br />
if not set -q __fish_git_prompt_color_branch<br />
set -g __fish_git_prompt_color_branch brmagenta<br />
end<br />
if not set -q __fish_git_prompt_showupstream<br />
set -g __fish_git_prompt_showupstream "informative"<br />
end<br />
if not set -q __fish_git_prompt_showdirtystate<br />
set -g __fish_git_prompt_showdirtystate "yes"<br />
end<br />
if not set -q __fish_git_prompt_color_stagedstate<br />
set -g __fish_git_prompt_color_stagedstate yellow<br />
end<br />
if not set -q __fish_git_prompt_color_invalidstate<br />
set -g __fish_git_prompt_color_invalidstate red<br />
end<br />
if not set -q __fish_git_prompt_color_cleanstate<br />
set -g __fish_git_prompt_color_cleanstate brgreen<br />
end<br />
<br />
printf '%s%s %s%s%s%s ' (set_color $fish_color_host) (prompt_hostname) (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) (__fish_git_prompt)<br />
<br />
if not test $last_status -eq 0<br />
set_color $fish_color_error<br />
end<br />
echo -n '$ '<br />
set_color normal<br />
end<br />
</nowiki>}}<br />
<br />
However, this is now deprecated, see [https://github.com/fish-shell/fish-shell/blob/master/share/functions/__fish_git_prompt.fish fish-shell git].<br />
Alternatively, the [https://mariuszs.github.io/blog/2013/informative_git_prompt.html Informative Git Prompt] has now been built into fish and can be activated from fish_config if so desired.<br />
<br />
=== Color the hostname in the prompt in SSH ===<br />
<br />
To color the hostname in the prompt dynamically whenever connected through SSH, add the following lines in either the {{ic|fish_prompt}} function or the fish configuration file, here using the red color:<br />
<br />
{{hc|~/.config/fish/functions/fish_prompt.fish|<br />
...<br />
if set -q SSH_TTY<br />
set -g fish_color_host brred<br />
end<br />
...}}<br />
<br />
=== Evaluate ssh-agent ===<br />
<br />
In fish, {{ic|eval (ssh-agent)}} generate errors due to how variables are set. To work around this, use the csh-style option {{ic|-c}}:<br />
<br />
$ eval (ssh-agent -c)<br />
<br />
=== The "command not found" hook ===<br />
<br />
Fish includes a "command not found" hook that will automatically search the official repositories, when entering an unrecognized command. This hook will be run using {{Pkg|pkgfile}}, falling back to {{ic|pacman -F}} if it is not installed.<br />
<br />
Since 3.2.2, "command not found" will not fallback to {{ic|pacman -F}} by default due to its [https://github.com/fish-shell/fish-shell/issues/7841 bad performance].<br />
<br />
If the delay this behavior introduces is undesirable, this hook can be overridden by redefining {{ic|fish_command_not_found}} so that it only prints an error message:<br />
$ function fish_command_not_found<br />
__fish_default_command_not_found_handler $argv[1]<br />
end<br />
<br />
To make this change permanent, the {{ic|funcsave}} built-in can be used:<br />
$ funcsave fish_command_not_found<br />
<br />
=== Remove a process from the list of jobs ===<br />
<br />
''fish'' terminates any jobs put into the background when fish terminates. To keep a job running after fish terminates, first use the {{ic|disown}} builtin. For example, the following starts {{ic|firefox}} in the background and then disowns it:<br />
<br />
$ firefox &<br />
$ disown<br />
<br />
This means firefox will not be closed when the fish process is closed. See {{man|1|disown|url=}} in ''fish'' for more details.<br />
<br />
=== Set a persistent alias ===<br />
<br />
To quickly make a persistent alias, one can simply use the method showed in this example:<br />
$ alias lsl "ls -l"<br />
$ funcsave lsl<br />
Since fish version 3.0, alias support --save(-s) option.<br />
$ alias -s lsl "ls -l"<br />
<br />
This will create the function:<br />
function lsl<br />
ls -l $argv<br />
end<br />
<br />
and will set the alias as a persistent shell function. To see all functions and/or edit them, one can simply use {{ic|fish_config}} and look into the ''Function'' tab in the web configuration page.<br />
<br />
For more detailed information, see [https://fishshell.com/docs/current/cmds/alias.html alias - create a function — fish-shell].<br />
<br />
== See also ==<br />
<br />
* https://fishshell.com/ - Home page<br />
* https://fishshell.com/docs/current/ - Documentation<br />
* https://hyperpolyglot.org/unix-shells - Shell grammar correspondence table ("shell rosetta")<br />
* https://github.com/fish-shell/fish-shell - fish on GitHub</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Dunst&diff=675992Dunst2021-06-06T17:54:19Z<p>Thiagowfx: /* Dunst fails to start via systemd */ add tip about /etc/X11/xinit/xinitrc.d/50-systemd-user.sh</p>
<hr />
<div>[[Category:X server]]<br />
[[ja:Dunst]]<br />
[[pl:Dunst]]<br />
{{Related articles start}}<br />
{{Related|Desktop Notifications}}<br />
{{Related articles end}}<br />
<br />
[https://dunst-project.org/ Dunst] is a lightweight replacement for the notification-daemons provided by most desktop environments.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|dunst}} package. <br />
<br />
An example configuration file is included at {{ic|/etc/dunst/dunstrc}}. Copy this file to {{ic|~/.config/dunst/dunstrc}} and edit it accordingly.<br />
<br />
Launch {{ic|/usr/bin/dunst}} and make sure your window manager or desktop environment starts it on startup/login.<br />
<br />
{{Note|It may seem like there is no need to manually start dunst, as it may get autostarted by dbus-daemon when programs send notifications through D-Bus. However, the notification service frequently has multiple daemons installed, and there is no way to know which daemon will be autostarted. The dbus-daemon maintainers explicitly warn against relying on autostart for multiple-provider services.}}<br />
<br />
== Appearance ==<br />
<br />
Dunst allows for the use of html markup in notifications. Some examples are bold, italics, strikethrough and underline. For a complete reference see [https://developer.gnome.org/pygtk/stable/pango-markup-language.html]. HTML can be stripped from notifications if {{ic|markup}} is set to {{ic|none}}.<br />
<br />
The formatting of the notification can be specified. Options are as follows:<br />
%a appname<br />
%s summary<br />
%b body<br />
%i iconname (including its path)<br />
%I iconname (without its path)<br />
%p progress value if set ([ 0%] to [100%]) or nothing<br />
<br />
These can be used in conjunction with HTML markup. For example the {{ic|format}} can be set to {{ic|<nowiki><b>%s</b>\n%b</nowiki>}} for a bolded notification summary, a newline and the body unformatted.<br />
<br />
=== Icon sets ===<br />
<br />
Icons are set in the option {{ic|icon_path}}. Status, devices and legacy icons are needed. By default, Dunst looks for the {{Pkg|gnome-icon-theme}} icons. For example, to use {{Pkg|adwaita-icon-theme}} (gnome-icon-theme's successor), instead:<br />
<br />
icon_path = /usr/share/icons/Adwaita/16x16/status/:/usr/share/icons/Adwaita/16x16/devices/:/usr/share/icons/Adwaita/16x16/legacy/<br />
<br />
== Shortcuts ==<br />
<br />
Dunst can be controlled with ''dunstctl''. You can update your [[keyboard shortcuts]] to call ''dunstctl''.<br />
<br />
For example, to close all notifications:<br />
$ dunstctl close-all<br />
<br />
To show history:<br />
$ dunstctl history-pop<br />
<br />
== Rules ==<br />
<br />
You can create rules in your dunstrc file which match certain notifications and then perform an action on it such as executing a script.<br />
<br />
=== Filtering ===<br />
<br />
To create a new rule create a new section with a custom name in your config file. <br />
In that section you can now use the attributes appname, summary, body, icon, category, match_transient and msg_urgency to match the <br />
notification.<br />
Globbing is supported. See [[#Scripting|Scripting]] for an example.<br />
Start dunst with the {{ic|-print}} option to find out useful information about a notification to write proper rules.<br />
<br />
=== Modifying ===<br />
<br />
When a notification is matched you can perform certain actions on it like modifying the format string, which is especially<br />
useful if you want to completely ignore certain notifications. <br />
In that case simply add the line {{ic|1=format=""}} to your rule.<br />
<br />
Another useful feature is if you want to keep certain notifications out of your history for example if you use dunst <br />
as a [[#Using dunstify as volume/brightness level indicator|Volume indicator]].<br />
To achieve this simply add {{ic|1=history_ignore=yes}} to your rule.<br />
<br />
=== Scripting ===<br />
<br />
Dunst can be configured to run scripts based on certain notification content. Here is an example using Dunst to run a script when someone from {{Pkg|pidgin}} signs on:<br />
<br />
[signed_on]<br />
appname = Pidgin<br />
summary = "*signed on*"<br />
urgency = low<br />
script = do_something.sh<br />
<br />
The specified script will be passed the following parameters in that order: appname, summary, body, icon, urgency.<br />
<br />
== Disable dunst temporarily ==<br />
<br />
To disable dunst temporarily there are two options.<br />
<br />
;Use {{ic|dunstctl}}<br />
:You can use {{ic|dunstctl set-paused true/false/toggle}} to disable/reenable or toggle pausing notifications. Use {{ic|dunstctl is-paused}} to check if dunst is currently running or paused.<br />
<br />
;Use {{ic|killall}}<br />
:Use {{ic|killall -SIGUSR1 dunst}} to disable and {{ic|killall -SIGUSR2 dunst}} to reenable<br />
<br />
Once paused dunst will hold back all notifications. <br />
After enabling dunst again all held back notifications will be displayed.<br />
<br />
== Dunstify ==<br />
<br />
Dunstify is an alternative to the [[Desktop notifications#Usage in programming|notify-send]] command<br />
which is completely compatible to notify-send and can be used alongside it, but offers some more features.<br />
Dunstify works only with the [[Dunst]] notification daemon.<br />
<br />
Additionally to the options available in notify-send, dunstify offers some more features like IDs and actions.<br />
<br />
=== Replacing notifications ===<br />
<br />
You can assign an ID to a notification by calling dunstify with the {{ic|-r ID}} option, where {{ic|ID}} must be an integer.<br />
If a notification with that ID already exists it will be replaced with the new one.<br />
You may also close a notification with {{ic|1=dunstify -C ID}}.<br />
<br />
However, for most use cases, implementing tags is preferred over micromanaging IDs because the latter option has many hidden pitfalls [https://github.com/dunst-project/dunst/issues/672]. Replacing IDs may be considered for debugging and for very complex notification senders instead of common practice [https://github.com/dunst-project/dunst/issues/672#issuecomment-554530659].<br />
<br />
Notifications with the same tag ("test" in this example) are replaced without having to care for IDs.<br />
<br />
$ dunstify -h string:x-dunst-stack-tag:test Test -A 'tested,default'<br />
$ dunstify -h string:x-dunst-stack-tag:test Testing<br />
<br />
=== Actions ===<br />
<br />
You can define actions which can be invoked directly from the notification by specifying one or more {{ic|1=--action=action,label}} parameters.<br />
For instance:<br />
dunstify --action="replyAction,reply" "Message received"<br />
<br />
The user can then access the specified actions via Dunst's context menu. The call to dunstify will block until either the notification disappears or an action is selected. In the former case dunstify will return 1 if the notification timed out and 2 if it was dismissed manually [https://developer.gnome.org/notification-spec/#signals]. In the latter case it returns the action which was selected by the Dunst context menu.<br />
<br />
In addition to invoking actions with the context menu, you may also define how mouse events invoke actions [https://github.com/dunst-project/dunst/blob/3f3082efb3724dcd369de78dc94d41190d089acf/dunstrc#L237]. This allows Dunst to be used interactively, as was suggested in [https://github.com/dunst-project/dunst/issues/163#issuecomment-573191650]. When a notification has only one action, or when an action is named "default", that action may be invoked by middle-clicking the notification (by default or when {{ic|dunstrc}} defines {{ic|<nowiki>mouse_middle_click = do_action</nowiki>}}).<br />
<br />
{{bc|<nowiki><br />
reply_action () {}<br />
forward_action () {}<br />
handle_dismiss () {}<br />
<br />
ACTION=$(dunstify --action="default,Reply" --action="forwardAction,Forward" "Message Received")<br />
<br />
case "$ACTION" in<br />
"default")<br />
reply_action<br />
;;<br />
"forwardAction")<br />
forward_action<br />
;;<br />
"2")<br />
handle_dismiss<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using dunstify as volume/brightness level indicator ===<br />
<br />
You can use the replace id feature to implement a simple volume or brightness indicator notification like in this picture [https://i.postimg.cc/j2CDkS1H/screen1712.png].<br />
<br />
To realize that volume indicator place the following script somewhere on your {{ic|PATH}}.<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
# changeVolume<br />
<br />
# Arbitrary but unique message id<br />
msgId="991049"<br />
<br />
# Change the volume using alsa(might differ if you use pulseaudio)<br />
amixer -c 0 set Master "$@" > /dev/null<br />
<br />
# Query amixer for the current volume and whether or not the speaker is muted<br />
volume="$(amixer -c 0 get Master | tail -1 | awk '{print $4}' | sed 's/[^0-9]*//g')"<br />
mute="$(amixer -c 0 get Master | tail -1 | awk '{print $6}' | sed 's/[^a-z]*//g')"<br />
if [[ $volume == 0 || "$mute" == "off" ]]; then<br />
# Show the sound muted notification<br />
dunstify -a "changeVolume" -u low -i audio-volume-muted -r "$msgId" "Volume muted" <br />
else<br />
# Show the volume notification<br />
dunstify -a "changeVolume" -u low -i audio-volume-high -r "$msgId" \<br />
-h int:value:"$volume" "Volume: ${volume}%"<br />
fi<br />
<br />
# Play the volume changed sound<br />
canberra-gtk-play -i audio-volume-change -d "changeVolume"<br />
</nowiki>}}<br />
<br />
Now simply bind {{ic|changeVolume 2dB+ unmute}} etc. to some hotkey and you are done. You might also want to make dunst ignore these type of notifications in its history. See [[#Modifying]].<br />
<br />
=== Overwrite previous notification ===<br />
<br />
For some notifications (for example sound or brightness), you might want to overwrite the previous notification. You can either use the Dunst method in [[#Replacing notifications]] or refer to [[Desktop notifications#Replace previous notification]] for a more general example.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Dunst fails to start via systemd ===<br />
<br />
When using dunst without a Display Manager, the {{ic|DISPLAY}} environment variable might not be correctly set.[https://github.com/dunst-project/dunst/issues/347]<br />
<br />
To fix this, add the following to your {{ic|.xinitrc}}:<br />
systemctl --user import-environment DISPLAY<br />
<br />
{{Tip|This is done automatically as part of {{ic|/etc/X11/xinit/xinitrc.d/50-systemd-user.sh}} that comes with recent versions of [[systemd]].}}<br />
<br />
=== Non-matching font sizes (Emojis much larger than text) ===<br />
<br />
This is caused by {{Pkg|fontconfig}} not rescaling bitmap fonts. This is usually only noticed with certain emoji fonts (e.g. {{Pkg|noto-fonts-emoji}})<br />
<br />
To solve, simply run:<br />
# ln -s /etc/fonts/conf.avail/10-scale-bitmap-fonts.conf /etc/fonts/conf.d/<br />
<br />
and restart Dunst.</div>Thiagowfxhttps://wiki.archlinux.org/index.php?title=Systemd/Journal&diff=675849Systemd/Journal2021-06-06T04:33:08Z<p>Thiagowfx: /* Filtering output */ nit: style, use $ instead of # for the --user example</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Logging]]<br />
[[es:Systemd (Español)/Journal]]<br />
[[ja:Systemd/ジャーナル]]<br />
[[pt:Systemd (Português)/Journal]]<br />
[[ru:Systemd (Русский)/Journal]]<br />
[[zh-hans:Systemd (简体中文)/Journal]]<br />
''systemd'' has its own logging system called the journal; running a separate logging daemon is not required. To read the log, use:<br />
<br />
# journalctl<br />
<br />
In Arch Linux, the directory {{ic|/var/log/journal/}} is a part of the {{Pkg|systemd}} package, and the journal (when {{ic|1=Storage=}} is set to {{ic|auto}} in {{ic|/etc/systemd/journald.conf}}) will write to {{ic|/var/log/journal/}}. If that directory is deleted, ''systemd'' will '''not''' recreate it automatically and instead will write its logs to {{ic|/run/systemd/journal}} in a nonpersistent way. However, the folder will be recreated if {{ic|1=Storage=persistent}} is added to {{ic|journald.conf}} and {{ic|systemd-journald.service}} is [[restart]]ed (or the system is rebooted).<br />
<br />
Systemd journal classifies messages by [[#Priority level|Priority level]] and [[#Facility|Facility]]. Logging classification corresponds to classic [[wikipedia:Syslog|Syslog]] protocol ([https://tools.ietf.org/html/rfc5424 RFC 5424]).<br />
<br />
== Priority level ==<br />
<br />
A syslog severity code (in systemd called priority) is used to mark the importance of a message [https://tools.ietf.org/html/rfc5424#section-6.2.1 RFC 5424 Section 6.2.1].<br />
<br />
{| class="wikitable"<br />
|-<br />
! Value !! Severity !! Keyword !! Description || Examples<br />
|-<br />
| 0 || Emergency || emerg || System is unusable || Severe Kernel BUG, [[Systemd-coredump|systemd dumped core]].<br>This level should not be used by applications.<br />
|-<br />
| 1 || Alert || alert || Should be corrected immediately || Vital subsystem goes out of work. Data loss. <br>{{ic|kernel: BUG: unable to handle kernel paging request at ffffc90403238ffc|}}.<br />
|-<br />
| 2 || Critical || crit || Critical conditions || Crashes, coredumps. Like familiar flash:<br>{{ic|systemd-coredump[25319]: Process 25310 (plugin-containe) of user 1000 dumped core}}<br>Failure in the system primary application, like X11. <br />
|-<br />
| 3 || Error || err || Error conditions || Not severe error reported:<br>{{ic|kernel: usb 1-3: 3:1: cannot get freq at ep 0x84}},<br>{{ic|systemd[1]: Failed unmounting /var.}},<br>{{ic|libvirtd[1720]: internal error: Failed to initialize a valid firewall backend}}<br />
|-<br />
| 4 || Warning || warning || May indicate that an error will occur if action is not taken. || A non-root file system has only 1GB free.<br>{{ic|org.freedesktop. Notifications[1860]: (process:5999): Gtk-WARNING **: Locale not supported by C library. Using the fallback 'C' locale}}.<br />
|-<br />
| 5 || Notice || notice || Events that are unusual, but not error conditions. || {{ic|systemd[1]: var.mount: Directory /var to mount over is not empty, mounting anyway}},<br>{{ic|gcr-prompter[4997]: Gtk: GtkDialog mapped without a transient parent. This is discouraged}}<br />
|-<br />
| 6 || Informational || info || Normal operational messages that require no action. || {{ic|lvm[585]: 7 logical volume(s) in volume group "archvg" now active}}<br />
|-<br />
| 7 || Debug || debug || Information useful to developers for debugging the application. || {{ic|kdeinit5[1900]: powerdevil: Scheduling inhibition from ":1.14" "firefox" with cookie 13 and reason "screen"}}<br />
|}<br />
<br />
These rules are recommendations, and the priority level of a given error is at the application developer's discretion. It is always possible that the error will be at a higher or lower level than expected.<br />
<br />
== Facility ==<br />
<br />
A syslog facility code is used to specify the type of program that is logging the message [https://tools.ietf.org/html/rfc5424#section-6.2.1 RFC 5424 Section 6.2.1].<br />
<br />
{| class="wikitable"<br />
! Facility code !! Keyword !! Description !! Info<br />
|-<br />
| 0 || kern || Kernel messages<br />
|-<br />
| 1 || user || User-level messages<br />
|-<br />
| 2 || mail || Mail system || Archaic POSIX still supported and sometimes used (for more {{man|1|mail}})<br />
|-<br />
| 3 || daemon || System daemons || All daemons, including systemd and its subsystems<br />
|-<br />
| 4 || auth || Security/authorization messages || Also watch for different facility 10<br />
|-<br />
| 5 || syslog || Messages generated internally by syslogd || For syslogd implementations (not used by systemd, see facility 3)<br />
|-<br />
| 6 || lpr || Line printer subsystem (archaic subsystem)<br />
|-<br />
| 7 || news || Network news subsystem (archaic subsystem)<br />
|-<br />
| 8 || uucp || UUCP subsystem (archaic subsystem)<br />
|-<br />
| 9 || || Clock daemon || systemd-timesyncd<br />
|-<br />
| 10 || authpriv || Security/authorization messages || Also watch for different facility 4<br />
|-<br />
| 11 || ftp || FTP daemon<br />
|-<br />
| 12 || - || NTP subsystem<br />
|-<br />
| 13 || - || Log audit<br />
|-<br />
| 14 || - || Log alert<br />
|-<br />
| 15 || cron || Scheduling daemon<br />
|-<br />
| 16 || local0 || Local use 0 (local0)<br />
|-<br />
| 17 || local1 || Local use 1 (local1)<br />
|-<br />
| 18 || local2 || Local use 2 (local2)<br />
|-<br />
| 19 || local3 || Local use 3 (local3)<br />
|-<br />
| 20 || local4 || Local use 4 (local4)<br />
|-<br />
| 21 || local5 || Local use 5 (local5)<br />
|-<br />
| 22 || local6 || Local use 6 (local6)<br />
|-<br />
| 23 || local7 || Local use 7 (local7)<br />
|}<br />
<br />
Useful facilities to watch: 0, 1, 3, 4, 9, 10, 15.<br />
<br />
== Filtering output ==<br />
<br />
''journalctl'' allows for the filtering of the output by specific fields. If there are many messages to display or filtering of large time span has to be done, the output of this command can be extensively delayed.<br />
<br />
Examples:<br />
<br />
* Show all messages from this boot: {{bc|# journalctl -b}} However, often one is interested in messages not from the current, but from the previous boot (e.g. if an unrecoverable system crash happened). This is possible through optional offset parameter of the {{ic|-b}} flag: {{ic|journalctl -b -0}} shows messages from the current boot, {{ic|journalctl -b -1}} from the previous boot, {{ic|journalctl -b -2}} from the second previous and so on – you can see the list of boots with their numbers by using {{ic|journalctl --list-boots}}. See {{man|1|journalctl}} for a full description; the semantics are more powerful than indicated here.<br />
* Include explanations of log messages from the message catalog where available: {{bc|# journalctl -x}} Note that this feature should not be used when attaching logs to bug reports and support threads, as to limit extraneous output. You can list all known catalog entries by running {{ic|journalctl --list-catalog}}.<br />
* Show all messages from date (and optional time): {{bc|1=# journalctl --since="2012-10-30 18:17:16"}}<br />
* Show all messages since 20 minutes ago: {{bc|1=# journalctl --since "20 min ago"}}<br />
* Follow new messages: {{bc|# journalctl -f}}<br />
* Show all messages by a specific executable: {{bc|# journalctl /usr/lib/systemd/systemd}}<br />
* Show all messages by a specific process: {{bc|1=# journalctl _PID=1}}<br />
* Show all messages by a specific unit: {{bc|# journalctl -u man-db.service}}<br />
* Show all messages from user services by a specific unit: {{bc|$ journalctl --user -u dbus}}<br />
* Show kernel ring buffer: {{bc|1=# journalctl -k}}<br />
* Show only error, critical and alert priority messages: {{bc|# journalctl -p err..alert}} You can use numeric log level too, like {{ic|journalctl -p 3..1}}. If single number/log level is used, {{ic|journalctl -p 3}}, then all higher priority log levels are also included (i.e. 0 to 3 in this case).<br />
* Show auth.log equivalent by filtering on syslog facility: {{bc|1=# journalctl SYSLOG_FACILITY=10}}<br />
* If the journal directory (by default located under {{ic|/var/log/journal}}) contains a large amount of log data then {{ic|journalctl}} can take several minutes to filter output. It can be sped up significantly by using {{ic|--file}} option to force {{ic|journalctl}} to look only into most recent journal: {{bc|# journalctl --file /var/log/journal/*/system.journal -f}}<br />
<br />
See {{man|1|journalctl}}, {{man|7|systemd.journal-fields}}, or [http://0pointer.de/blog/projects/journalctl.html Lennart Poettering's blog post] for details.<br />
<br />
{{Tip|1=<br />
By default, ''journalctl'' truncates lines longer than screen width, but in some cases, it may be better to enable wrapping instead of truncating. This can be controlled by the {{ic|SYSTEMD_LESS}} [[environment variable]], which contains options passed to [[Core utilities#Essentials|less]] (the default pager) and defaults to {{ic|FRSXMK}} (see {{man|1|less}} and {{man|1|journalctl}} for details).<br />
<br />
By omitting the {{ic|S}} option, the output will be wrapped instead of truncated. For example, start ''journalctl'' as follows:<br />
<br />
$ SYSTEMD_LESS=FRXMK journalctl<br />
<br />
To set this behaviour as default, [[Environment variables#Per_user|export]] the variable from {{ic|~/.bashrc}} or {{ic|~/.zshrc}}.<br />
}}<br />
<br />
{{Tip|While the journal is stored in a binary format, the content of stored messages is not modified. This means it is viewable with ''strings'', for example for recovery in an environment which does not have ''systemd'' installed, e.g.:<br />
<br />
{{bc|$ strings /mnt/arch/var/log/journal/af4967d77fba44c6b093d0e9862f6ddd/system.journal {{!}} grep -i ''message''}}<br />
<br />
}}<br />
<br />
== Journal size limit ==<br />
<br />
If the journal is persistent (non-volatile), its size limit is set to a default value of 10% of the size of the underlying file system but capped at 4 GiB. For example, with {{ic|/var/log/journal/}} located on a 20 GiB partition, journal data may take up to 2 GiB. On a 50 GiB partition, it would max at 4 GiB. To confirm current limits on your system review {{ic|systemd-journald}} unit logs:<br />
<br />
# journalctl -b -u systemd-journald<br />
<br />
The maximum size of the persistent journal can be controlled by uncommenting and changing the following:<br />
<br />
{{hc|/etc/systemd/journald.conf|2=<br />
SystemMaxUse=50M<br />
}}<br />
<br />
It is also possible to use the drop-in snippets configuration override mechanism rather than editing the global configuration file. In this case, place the overrides under the {{ic|[Journal]}} header:<br />
<br />
{{hc|/etc/systemd/journald.conf.d/00-journal-size.conf|2=<br />
[Journal]<br />
SystemMaxUse=50M<br />
}}<br />
<br />
[[Restart]] the {{ic|systemd-journald.service}} after changing this setting to apply the new limit.<br />
<br />
See {{man|5|journald.conf}} for more info.<br />
<br />
=== Per unit size limit ===<br />
<br />
[[Edit]] the unit file for the service you wish to configure (for example sshd) and add {{ic|1=LogNamespace=ssh}} in the {{ic|[Service]}} section.<br />
<br />
Then create {{ic|/etc/systemd/journald@ssh.conf}} by copying {{ic|/etc/systemd/journald.conf}}. After that, edit {{ic|journald@ssh.conf}} and adjust {{ic|SystemMaxUse}} to your liking.<br />
<br />
[[Restart]]ing the service should automatically start the new journal service {{ic|systemd-journald@ssh.service}}. The logs from the namespaced service can be viewed with {{ic|journalctl --namespace ssh}}.<br />
<br />
See {{man|8|systemd-journald.service|JOURNAL NAMESPACES}} for details about journal namespaces.<br />
<br />
== Clean journal files manually ==<br />
<br />
Journal files can be globally removed from {{ic|/var/log/journal/}} using ''e.g.'' {{ic|rm}}, or can be trimmed according to various criteria using {{ic|journalctl}}. For example:<br />
<br />
* Remove archived journal files until the disk space they use falls below 100M: {{bc|1=# journalctl --vacuum-size=100M}}<br />
* Make all journal files contain no data older than 2 weeks. {{bc|1=# journalctl --vacuum-time=2weeks}}<br />
<br />
See {{man|1|journalctl}} for more info.<br />
<br />
== Journald in conjunction with syslog ==<br />
<br />
Compatibility with a classic, non-journald aware [[Syslog-ng|syslog]] implementation can be provided by letting ''systemd'' forward all messages via the socket {{ic|/run/systemd/journal/syslog}}. To make the syslog daemon work with the journal, it has to bind to this socket instead of {{ic|/dev/log}} ([https://lwn.net/Articles/474968/ official announcement]). <br />
<br />
The default {{ic|journald.conf}} for forwarding to the socket is {{ic|1=ForwardToSyslog=no}} to avoid system overhead, because [[rsyslog]] or [[syslog-ng]] pull the messages from the journal by [https://lists.freedesktop.org/archives/systemd-devel/2014-August/022295.html#journald itself]. <br />
<br />
See [[Syslog-ng#Overview]] and [[Syslog-ng#syslog-ng and systemd journal]], or [[rsyslog]] respectively, for details on configuration.<br />
<br />
== Forward journald to /dev/tty12 ==<br />
<br />
Create a [[Systemd#Editing provided units|drop-in directory]] {{ic|/etc/systemd/journald.conf.d}} and create a {{ic|fw-tty12.conf}} file in it:<br />
<br />
{{hc|1=/etc/systemd/journald.conf.d/fw-tty12.conf|2=<br />
[Journal]<br />
ForwardToConsole=yes<br />
TTYPath=/dev/tty12<br />
MaxLevelConsole=info<br />
}}<br />
<br />
Then [[restart]] {{ic|systemd-journald.service}}.<br />
<br />
== Specify a different journal to view ==<br />
<br />
There may be a need to check the logs of another system that is dead in the water, like booting from a live system to recover a production system. In such case, one can mount the disk in e.g. {{ic|/mnt}}, and specify the journal path via {{ic|-D}}/{{ic|--directory}}, like so:<br />
<br />
# journalctl -D ''/mnt''/var/log/journal -e</div>Thiagowfx