search

ente76 / 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.
GNU Affero General Public License v3.0
28 stars 0 forks source link
extension gnome menu

readme

buy me a coffee donate@paypal

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.

example.png

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

menu

The menu is an array of items, each being one of the following types.

1. command
2. switch

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
4. 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:

gtk3-icon-browser is an app that shows a selection of system icons. Personally I use glade to browse the local icons.

Change History

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.