This repository has been moved to GitLab

Guillotine

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 icon
• logLevel (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 show
• icon (string): name of a system icon to show
• command (string): command to execute
• instancing (string): how to handle a running process. Either of the following values is valid:
  • singleInstance: the menu item is disabled until the old process finished
  • multipleInstances (default): no restrictions; multiple instances may be executed in parallel
• killOnDisable (boolean): whether the process gets killed when the extension gets disabled, defaults to true

2. switch

• type: switch
• title (string): title to show
• icon (string): name of a system icon to show
• start (string): command to execute when switching from off to on
• stop (string): command to execute when switching from on to off
• check (string): command to run when checking the toggle stat
  • exit code 0: the service is currently running, the switch is on
  • other exit code: the service is stopped, the switch is off
• interval_s (number): time between 2 checks in seconds
• interval_ms (number): time between 2 checks in milliseconds
• interval (number): [deprecated] same as interval_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 show
• icon (string): name of a system icon to show
• items ([]): 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:

• ~