GitLab
This repository has been moved toGuillotine
Guillotine is a gnome extension designed for efficiently carrying out executions of commands from a customizable menu. Simply speaking: it is a highly customizable menu that enables you to launch commands and toggle services.
Configuration
If no configuration is found, a default config is restored at ~/.config/guillotine.json
. Whenever the configuration file changes, the extension reloads automatically.
The configuration has two segments: settings
and menu
.
Example
{
"settings": {
"loglevel": "warning"
},
"menu": [
{
"type": "command",
"title": "teamspeak",
"command": "sh -c 'pactl set-card-profile $(pactl list short | grep bluez_card | cut -f1) headset_head_unit;pactl set-default-sink $(pactl list short sinks | grep alsa_output | cut -f1);teamspeak3'",
"icon": "audio-headset-symbolic"
},
{
"type": "separator"
},
{
"type": "submenu",
"title": "code",
"icon": "com.visualstudio.code.oss",
"items": [
{
"type": "command",
"title": "guillotine",
"command": "code Projects/guillotine",
"icon": "guillotine-symbolic",
"killOnDisable": false
},
{
"type": "command",
"title": "kitsch",
"command": "code Projects/kitsch",
"icon": "guillotine-symbolic",
"killOnDisable": false
}
]
},
{
"type": "separator"
},
{
"type": "submenu",
"title": "Remote",
"icon": "network-server-symbolic",
"items": [
{
"type": "command",
"title": "ssh remote.server.tld",
"command": "gnome-terminal -e 'ssh remote.server.tld'",
"icon": "preferences-other-symbolic",
"killOnDisable": false
},
{
"type": "command",
"title": "nautilus remote.server.tld",
"command": "nautilus ssh://remote.server.tld",
"instancing": "singleInstance",
"icon": "preferences-other-symbolic",
"killOnDisable": false
}
]
},
{
"type": "separator"
},
{
"type": "submenu",
"title": "Guillotine",
"icon": "guillotine-symbolic",
"items": [
{
"type": "command",
"title": "Configuration",
"command": "code .config/guillotine.json",
"icon": "preferences-other-symbolic",
"killOnDisable": false
},
{
"type": "command",
"title": "Log",
"command": "gnome-terminal -e 'journalctl -f GNOME_SHELL_EXTENSION_UUID=guillotine@fopdoodle.net'",
"instancing": "singleInstance",
"icon": "emblem-documents-symbolic",
"killOnDisable": false
},
{
"type": "command",
"title": "Log Gnome Shell",
"command": "gnome-terminal -e 'journalctl -f _COMM=gnome-shell' ",
"instancing": "singleInstance",
"icon": "emblem-documents-symbolic",
"killOnDisable": false
}
]
},
{
"type": "separator"
},
{
"type": "switch",
"title": "syncthing",
"start": "systemctl --user start syncthing.service",
"stop": "systemctl --user stop syncthing.service",
"check": "systemctl --user is-active syncthing.service",
"icon": "emblem-synchronizing-symbolic",
"interval_s": 10
}
]
}
settings
icon
(string): name of a system icon to show as the status iconlogLevel
(string): the log level of the extenions. Any of the following values is valid:debug
info
warning
(default)error
notificationLevel
(string): the notification level of the extension. Any of the following values is valid:- not defined (default): notifications are disabled
debug
info
warning
error
menu
The menu is an array of items, each being one of the following types.
1. command
type
:command
title
(string): title to showicon
(string): name of a system icon to showcommand
(string): command to executeinstancing
(string): how to handle a running process. Either of the following values is valid:singleInstance
: the menu item is disabled until the old process finishedmultipleInstances
(default): no restrictions; multiple instances may be executed in parallel
killOnDisable
(boolean): whether the process gets killed when the extension gets disabled, defaults totrue
2. switch
type
:switch
title
(string): title to showicon
(string): name of a system icon to showstart
(string): command to execute when switching from off to onstop
(string): command to execute when switching from on to offcheck
(string): command to run when checking the toggle stat- exit code
0
: the service is currently running, the switch ison
- other exit code: the service is stopped, the switch is
off
- exit code
interval_s
(number): time between 2 checks in secondsinterval_ms
(number): time between 2 checks in millisecondsinterval
(number): [deprecated] same asinterval_ms
If no interval is defined, it defaults to interval_s
at 10 seconds. If multiple intervals are defined, interval_s
has highest priority. The interval is the length of the pause between 2 checks, i.e. if the command assigned to check
takes 1s to execute and interval_s
is set to 2, the command is spawned every 3s. interval_s
is less precise as interval_ms
also in a way that the interval is not guaranteed to be precisely equal to the requested period. In return interval_s
is supposed to consume less energy. interval_ms
may become deprecated in the near future if interval_s
prooves to be superior.
WARNING: a (very) short interval may cause Gnome to become unresponsive.
3. submenu
type
:switch
title
(string): title to showicon
(string): name of a system icon to showitems
([]): an arry of items, see menu
4. separator
type
:separator
Commands
start
, stop
, check
and command
are commands to be executed. It is highly recommended to test these commands extensively in a shell before adjusting the configuration. A shell that actually shows return codes (e.g. zsh
with powerlevel10k
) is recommended especially when testing switches.
The return code of all commands is checked. For start
, stop
and command
a non-zero return code will currently only result in a log entry. For check
the return code determines the switch state and no log entry is created.
There is no shell environment that commands are executed in. To use shell syntax, simply start any shell of your preference and ask the shell to execute the command: "check": "sh -c 'if [ -f /folder/file ]; then exit 0; else exit 1; fi'"
which could be boiled down to "check": "sh -c 'exit $([ -f /folder/file ])'"
.
Executing multiple commands with a single menu item works by calling a shell as well: "command": "sh -c 'command1; command2'"
.
Executing commands directly or using a shell will happen in background. If you need foreground feedback, execute a terminal and pass the actual command to the terminal: "command": "gnome-terminal -e 'journalctl -f GNOME_SHELL_EXTENSION_UUID=guillotine@fopdoodle.net'"
.
The options singleInstance
and killOnDisable
have no impact on background processes, i.e., these options don't work on something like sh -c 'long-running-command &'
. Some applications are implicitly behaving like this, e.g. firefox & gnome-terminal.
A switch is strictly running a single instance of all commands. You won't be able to access the menu item while the start
or the stop
command are executed. To be more precise: a start
and a stop
command will disable the menu and trigger a check
command. On return of the check
command the menu item gets enabled and switch to the correct state depending on the return code. The operation of a switch can be best observed on the following example: Initially the switch is in state off
. When manually switching to on
, the switch becomes disabled (can't be accessed). The start
command will be executed but it will always be considered a failure (return code != 0, an error is logged) and it will trigger an immediate check. The check command will last 10 seconds before returning that the switch is off
(return code != 0, no error is logged). The switch will be returned to state off
and the switch will be enabled for user input again.
"start": "sh -c 'exit 1'",
"stop": "sh -c 'exit 0'",
"check": "sh -c 'sleep 10;exit 1'"
Icons
Icons can be found by searching any subdirectory of the following directories:
- ~/.local/share/icons
- /usr/share/icons
gtk3-icon-browser
is an app that shows a selection of system icons. Personally I use glade to browse the local icons.
Change History
- v1: 26.01.2021
- initial version
- v2: 29.01.2021
- fixed a bug which prevented startup
- implemented "submenu"
- improved documentation
- v3: 31.01.2021
- extension icon
- icons for switches
- logging adjusted:
- switch-check adjusted to debug
- log level logging fixed
- v4: 01.02.2021
- metadata fixed / prepared for v4
- icon for extensions.gnome.org added
- button for buy-me-a-coffee added
- button for paypal donations added
- v5: 30.04.2021:
- configurable status icon (provided by hashstat)
- v6: 14.06.2021
- adjust gnome version number
- v7: 06.11.2021
- add gnome 41 compatibility (provided by aliakseiz)
- v8: 13.11.2021
- improve the documentation of commands
- implement exception handling for malformed commands
- implement the interval settings in s and ms granularity
- deprecated
interval
- deprecated
- implement shut down functionality for switch commands
- prepare a set of test cases
- implement notifications based on log entries with separate level filter
- removed
killBeforeRestart
option fromcommand
(complex functionality with limited use)- a notification will be raised if in use (this will be removed in the next version)
- v9: 13.11.2021
- fix a complaint from extension review
ToDo
The extension is considered stable. No further improvements are planned for now.
Contributors
License
Guillotine: a gnome extension designed for efficiently carrying out executions of commands from a customizable menu Copyright (C) 2021 Christian Klaue [mail@ck76.de]
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.
Individual licenses may be granted upon request.