SET-set-gdm-theme(1)

NAME
set-gdm-theme - a utility to set GDM theme and background

SYNOPSIS
set-gdm-theme -e|-h|-l|-lc|-m|-r

set-gdm-theme examples|help|list|list-colors|manual|reset

set-gdm-theme -s|set [theme] [image|color]

set-gdm-theme -b|backup -u|update|-r|restore

set-gdm-theme -x|extract [location] [default|distro-default]

DESCRIPTION
List available theme options for Gnome Dislplay Manager (GDM), and set GDM theme and background image. A theme, to be a valid theme for this program, should be located in /usr/share/themes/ and contain a subdirectory for gnome-shell. In simple words, a theme has to be a valid gnome-shell theme located in /usr/share/themes in order to be a valid GDM theme.

set-gdm-theme(1) has a smart backup system which backs up the default GDM theme (/usr/share/gnome-shell/gnome-shell-theme.gresource) because the file needs to be overwritten in order for other themes to be applied. It is a bit complicated and is discussed in detail in WARNING section.

SUBCOMMANDS

  -l,list
list available GDM themes. A theme has to be either the default gnome-shell theme or a valid gnome-shell theme stored in /usr/share/themes in order to show up in the list. A valid gnome-shell theme is a theme which has a subdirectory named gnome-shell with gnome-shell.css file present in it. This option will always show default theme as the first in the list.

  -lc,list-colors
list names of the colors that are accepted as GDM background.

  -s,set [theme] [image|color]
if provided, set [theme] as GDM theme and [image] as GDM background image or [color] as GDM background, where [theme] is the name of the theme, [image] is path to an image file and [color] is either the name of a color e.g. red, green, violet, etc or a color code like '#00F' or '#0a4d90' (qoutes are important).

Your choices for theme are 'default', all system-wide gnome-shell themes, and -b or --background. Your choices for an image are /path/to/image and 'none'. Both theme and image arguments are optional.

A list of acceptable color names can be obtained by running 'set-gdm-theme list-colors'.

If you provide name of a theme, it will be set as GDM theme. If you type -b or --background instead of a theme name, only GDM background will change. Similarly, if you provide a path to an image file, it will be used as GDM background. If you type 'none' instead of path to an image file, GDM background image will be removed and the background will be set according to the theme (usually a solid color).

If you don't provide anything after -s or set, set-gdm-theme(1) will provide you with a numbered list of all valid GDM themes on the system and you can choose a theme by typing its number. When you press Enter, set-gdm-theme(1) will set the theme with that number.

Examples:

set-gdm-theme set Yaru-dark
    will set Yaru-dark as GDM theme
set-gdm-theme -s default ~/Pictures/Sunset.jpg
    will set default GDM theme with ~/Pictures/Sunset.jpg as background
set-gdm-theme set -b ~/Pictures/Cat.jpg
    will set ~/Pictures/Cat.jpg as GDM background
set-gdm-theme -s Materia none
    will set Materia as GDM theme with no background image
set-gdm-theme -s -b blue
    will set GDM background to color 'blue'
set-gdm-theme -s -b '#aa442d'
    will set GDM background to color with color-code '#aa442d'
set-gdm-theme set
    will provide you with a list of themes to choose from and then set what you choose

  -r,reset
reset everything to the way it was before the use of set-gdm-theme(1) except for removing the backup it created. This option sets unmodified default GDM theme (/usr/share/gnome-shell/gnome-shell-theme.gresource.default) as GDM theme by moving it to its original place (/usr/share/gnome-shell/gnome-shell-theme.gresource), removes GDM background image file (/usr/share/gnome-shell/theme/gdm-background) which was created by set-gdm-theme(1), and sets set-gdm-theme.gresource name in update-alternatives(1) to auto.

  -b,backup {action}
update or restore backup of the default GDM theme. This additional backup can be very helpful if some other program or a bug in set-gdm-theme(1) messes up the default GDM theme. This option requires at least one action. The action choices are update and restore or their short forms -u and -r. For example,

set-gdm-theme -b update
    will update backup to the newest version of default GDM theme
set-gdm-theme backup -r
    will restore default GDM theme from the backup

  -x,extract [location] [default|distro-default]
extract the default or distro-default GDM theme to specified location if provided. If no location is provided, it is extracted to system-wide themes directory /usr/share/themes. If a theme name ('default' or 'distro-default') is provided after the location, provided theme is extracted to provided location. But, the 2nd argument to this option is practical only if your distro ships custom GDM theme as default and places actual default theme as something else (see /etc/gdm-tools/set-gdm-theme).

This can be helpful when you use some weird Gnome session such as ubuntu-session whose default gnome-shell theme is not the actual default gnome-shell theme provided by gnome. You cannot set default gnome-shell theme in Ubuntu unless you install 'gnome-session' and log in to Gnome (session) instead of Ubuntu (session). With this option, you will be able to set gnome-shell theme to the actual default gnome-shell theme even when in Ubuntu (session). It will be presented as 'Default-extracted' in gnome-tweaks app.

  -h,--help,help
print a short help message which provides program name, a short description of the program, and command options with a little description of each option too.

  -m,manual
show this manual page

  -e,examples
explain the usage of set-gdm-theme(1) with examples.

WARNING
GDM uses the file /usr/share/gnome-shell/gnome-shell-theme.gresource as its theme. We are going to call this file the 'default gresource file' for now. In order to set a theme as GDM theme, the default gresource file has to be replaced by the custom theme's gresource file. The default gresource file has to be backed up first if it is ever needed to be reused and it will surely be needed in future because user would want to set the default GDM theme at some point.

Other programs (that set and change GDM theme) backup the default gresource file only on the first run if they back it up at all. When user sets default theme using any of those programs, they set that backup as GDM theme. If Gnome gets upgraded, custom theme's gresource file is replaced with newer version of the default gresource file. Then you change GDM theme again to your preference. Since there is already a backup present on the system, those programs do not backup the newer version of default gresource file. Instead, they just replace it with a custom gresource file and keep using the old backup as default theme. When a major version upgrade happens to Gnome, it breaks compatibility with older version of default theme. But those programs keep using the incompatible, old backup of default theme(gresource file). In the end, their version of the default theme does not work correctly anymore.

To tackle the problem stated above, set-gdm-theme(1) uses a dual backup system i.e it keeps two backups of the default gresource. One backup is managed automatically by set-gdm-theme(1) (We will call it smart backup), and the other is created once on the first run and then managed manually with -b,backup option of set-gdm-theme(1) (We will call it manual backup). Whenever the word "backup" is used without specifying the type, manual backup is intended.

Smart backup is used as 'default' GDM theme in set-gdm-theme(1). set-gdm-theme(1) marks the theme it sets with a special file i.e. it packs the special file inside gresource file of that theme. The special file is used to distinguish a custom theme's gresource file from the default gresource file. So, if currently set gresource file does not have that special file, it is understood to be the default gresource file. Whenever set-gdm-theme(1) finds such a gresource file, it replaces the old smart backup with that file. As a result, when set-gdm-theme(1) runs after an upgrade to Gnome, smart backup gets upgraded too. Therefore, the smart backup is always up-to-date.

This smart backup comes with its limitations though. Since the other programs do not mark the theme they set with special identification file like set-gdm-theme(1) does, the file they replace default gresource with is recognized by set-gdm-theme(1) as a newer version of the default gresource file. Hence, it replaces the smart backup with that file and the theme set by other program is treated as the default theme. In this situation, the command 'set-gdm-theme set default' will set that theme as GDM theme instead of the actual default GDM theme. Manual backup is present there to help in such situations.

To avoid this situation, you can opt to use only one program to set GDM theme instead of using multiple programs on the system. If you don't like the program you are currently using or want to check out some other program, then before using the new program, you should use the previous program to set the default GDM theme. The other thing you can do is to backup the default gresource file by yourself before using any GDM theme changer. In this way, you will always have a backup of the default GDM theme even if some program messes up its backup. To do so, copy the default gresource file somewhere you won't accidently delete or forget. When some program messes up the default gresource file, you will just need to replace it with your own backup. set-gdm-theme(1) will automatically detect that as default gresource file and everything will be fine again.

In case you used some other program to set GDM theme, then installed and used set-gdm-theme(1) to set GDM theme, now set-gdm-theme(1) sets some other theme when you try to set the default GDM theme, the other program does not provide any way to set the default GDM theme, and you never backed up the default GDM theme manually; You can solve this problem by reinstalling the package 'gnome-shell-common' (and if that package is not available, then 'gnome-shell') and then updating set-gdm-theme(1)'s smart-backup by running 'set-gdm-theme set --background' and manual backup by running 'set-gdm-theme -b update'. This will fix everything. If you face the same problem again in future, just run the command 'set-gdm-theme -b restore' and that should fix it.

Note: In Debian/Ubuntu and derivatives, you can reinstall 'gnome-shell-common' by running the command 'sudo apt reinstall gnome-shell-common'.

However, if you only use set-gdm-theme(1) for changing GDM theme or background, no such problem is supposed to occur.

FILES
/etc/gdm-tools/set-gdm-theme.conf - The configuration file for set-gdm-theme command

/etc/gdm-tools/custom.css - Custom CSS to apply to every theme before setting it as GDM theme

SEE ALSO
set-gdm-theme --help

set-gdm-theme examples