Shell-independent command manager.

6.1 KiB

Raw Permalink Blame History

DOSH

Shell-independent command manager. Create your dosh.star file in the project folder and define your tasks, aliases, environments. Dosh will work like a CLI app reading your config file.

ENVIRONMENT VARIABLES

HELP OUTPUT

Help outputs consist of three parts: description, tasks, epilog. The tasks are generated reading your config but you can edit the other parts defining these variables:

HELP_DESCRIPTION
HELP_EPILOG

If you want to delete the description or epilog, define it as None.

OPERATING SYSTEM TYPE CHECKING

OS type variables to detect your current operating system. All variables return True or False. You can find many examples of use of these variables in the documentation.

IS_LINUX
IS_MACOS
IS_WINDOWS

SHELL TYPE CHECKING

Your current shell. All these variables return True or False. It's useful if you use shell-specific package like ohmyzsh.

IS_BASH
IS_PWSH
IS_ZSH

FUNCTIONS

GENERAL PURPOSE

The main purpose of dosh to write one script that works on multiple operating systems and shells. But it has to have a limit and it's nonsense to define functions for each command. So if you want to run a cli app (like exa, bat, helix, etc.), then you can use run for it:

run("echo 'hello, world!'")

if IS_MACOS or IS_LINUX:
    run_url("https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh")

if IS_WINDOWS:
    clone("https://github.com/coreybutler/nvm-windows.git")

FILE SYSTEM OPERATIONS

There are some ready-made functions both to keep the code readable and to make it work the same in every operating system. You know Windows prefers backslash as a path separator. This code will work on all operating systems:

if USER == "goedev":
    copy(HOME / "Workspace/goedev/emacs.d", HOME / ".emacs.d")

PACKAGE MANAGERS

There are many package managers and I'm not sure if we need to implement all of them. But at least I'm using these three of them mostly:

brew_install (for MacOS and Linux)
- packages: list of strings, required.
- cask: boolean, default is false.
- taps: list of strings, optional.
apt_install (for Debian based Linux distros)
- packages: list of strings, required.
winget_install (for Windows)
- packages: list of strings, required.

brew_install(["emacs", "helix"], cask=True, taps=["helix-editor/helix"])

FILE, FOLDER, COMMAND EXISTENCY: `exists`, `exists_command`

TODO...

LOGGING

You can manage the command outputs by defining the verbosity level. It's still possible to use print, but if you want to hide the command outputs completely or print them by the verbosity level, you have to use these logging functions:

debug
info
warning
error

info("if you don't want to see this message, you have to run dosh with the correct verbosity level.")

For more information about the verbosity parameter of dosh, type dosh --help (not help).

EXAMPLE CONFIGURATION

REPOS_DIR = HOME / "Workspace/goedev"
CONFIG_REPO_DIR = REPOS_DIR / "config"


def cmd_setup_my_os():
    """place my config files."""

    info("replace my config folder and home files.")
    copy(CONFIG_REPO_DIR / "config/*", HOME / ".config")
    copy(CONFIG_REPO_DIR / "tmp/home/.*", HOME)

    if IS_ZSH and not exists(HOME / ".oh-my-zsh"):
        debug("ohmyzsh is not installed yet.")
        run_url("https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh")

    clone("https://github.com/tmux-plugins/tpm", target=HOME / ".tmux/plugins/tpm", fetch=True)


def cmd_install_cli_apps():
    """install my favorite apps."""

    if IS_MACOS:
        brew_install(["git", "ripgrep", "bat", "exa", "miniconda", "emacs"])

    elif IS_LINUX:
        apt_install(["git", "ripgrep", "bat", "exa", "alacritty"])

    elif IS_WINDOWS:
        winget_install(["Git.Git", "Microsoft.WindowsTerminal", "Microsoft.VisualStudioCode"])

    else:
        error("What the hell are you using??")


def cmd_sync_repos(repos):
    """
    don't forget to push your changes before working on a different laptop.

    - repos: path of repositories. List[str], optional
    """
    repos = repos or get_folders(REPOS_DIR)

    for repo_dir in repo_dirs:
        result = sync(repo_dir)
        if result.status == STATUS_OK:
            info(result.message)
        else:
            error(message)

WHAT IF YOU TRY TO USE THIS CONFIG...

After you created your dosh.star file, you can see all available tasks with the command dosh help:

$ dosh help  # or just dosh
Tasks:
  > setup_my_os        place my config files.
  > install_cli_apps   install my favorite apps.
  > sync_repos         don't forget to push your changes before working on a different
                       laptop.
                       - repo_path: str, optional

$ dosh install_cli_apps
...

$ dosh sync_repos -- repo_path=yank
...

QUESTIONS

CAN I TRUST THIS PROJECT?

No. Don't trust any project. The source code is open, trust yourself and read the code.

BUT DO YOU USE THIS PROJECT YOURSELF?

Yes, I use multiple operating systems with different shells, and I'm too tired to write my scripts in multiple languages. This is why I created this project.

WHY DOESN'T DOSH HAVE ANY REMOVE COMMAND?

Because it's too dangerous! I don't use any remove command in my scripts indeed. If you really need a remove command, you can run it with run. But remember, contributors of this project don't guarantee anything.

IS THERE ANY SYNTAX HIGHLIGHTER, EDITOR EXTENSION, OR LINTER FOR D...

Open your dosh.star file in your favorite editor with Python - Bazel - Starlark mode and just write your f*cking script now. Or take a look at this link: https://github.com/bazelbuild/starlark/blob/master/users.md

CONTRIBUTION

Install poetry and pre-commit first, then:

$ poetry install
$ poetry run dosh       # run dosh without instaling.
$ poetry run poe lint   # run pre-commit hooks manually.
$ poetry run poe test   # run unit tests.
$ poetry run poe build  # build and generate self-executable file.

6.1 KiB Raw Permalink Blame History