Rush - Personal Package Manager

_______                       ______  
____  /  ___________  ___________  /_ 
___  /   __  ___/  / / /_  ___/_  __ \
__  /    _  /   / /_/ /_(__  )_  / / /
_  /     /_/    \__,_/ /____/ /_/ /_/ 
/_/      Personal Package Manager

Rush is a bash script that executes other scripts (bash or other languages) from compatible GitHub repositories or local folders. It provides a simple command line interface for downloading, updating and running these scripts.

See this minimal sample rush repo, or a real life example repo at DannyBen/rush-repo.

Rush was designed to easily allow bootstrapping of new linux machines with your desired configuration and installed packages and to "normalize" the way you install things.

Rush was developed using the Bashly Command Line Framework.

Prerequisites

Bash 4.0 or higher (brew install bash on mac).
curl
git

Installation

Installing using the setup script

This setup script will download the rush executable to /usr/local/bin/ and install an autocomplete script in the bash completions directory.

$ curl -Ls get.dannyb.co/rush/setup | bash

Feel free to inspect the setup script before running.

Installing manually

Download the rush script to /usr/local/bin/ or anywhere in your PATH, and make it executable.

If you wish to have all package name auto-completed for all rush commands, add this line to your startup script (for example: ~/.bashrc):

complete -W '$(rush list -s)' rush

Quick Start

After installing, you can follow these steps to quickly see how it works:

# Clone a sample package repository
$ rush clone dannyben/rush-repo-template --name sample

# View the config file and verify it was added
$ rush config

# View list of packages
$ rush list

# Install (execute) a sample package
# (All packages in the sample repository only print some messages)
$ rush get sample:hello 

# Optionally, make this repository the default
$ rush default sample

# And now you can omit the repository name when getting a package
$ rush get hello

# Since `get` is the default command, the above command is the same as
$ rush hello

In case you prefer testing Rush in a clean, isolated docker environment, you can use this docker image, which has Rush copied to its path:

$ docker run --rm -it --entrypoint bash dannyben/rush
> rush --help

Usage

$ rush --help

rush - Personal package manager

Usage:
  rush COMMAND
  rush [COMMAND] --help | -h
  rush --version | -v

Repository Commands:
  add           Register a local repository
  remove        Unregister a local repository

Git Commands:
  clone         Clone a GitHub package repository
  pull          Git pull one or all repositories
  push          Git push one or all repositories

Config Commands:
  config        Show or edit the configuration file
  default       Set a default repository

Package Commands:
  get           Install a package (default)
  undo          Uninstall a package
  snatch        Install a package from a remote repo
  copy          Copy a package between local repositories
  info          Show information about a package
  list          Show packages in one or all repositories
  search        Search in package names and info files
  edit          Edit package files
  show          Show package files

Internal Commands:
  completions   Generate bash completions

Options:
  --help, -h
    Show this help

  --version, -v
    Show version number

Environment Variables:
  RUSH_CONFIG
    Location of the rush config file
    Default: ~/rush.ini

  RUSH_ROOT
    Location of the default base directory for cloning repositories.

    Default: ~/rush-repos

Building your own Rush repository

Create your own repository, either manually or by using this Github template. In any case, it is recommended you name your repository rush-repo.

To create a repository manually, follow these steps:

Create a new repository on GitHub, named rush-repo.
Each folder you create in this repository is considered a package.
Each package needs to have these files:
- An executable script named main - this will be executed when running rush get yourpackage.
- A plain text file called info - this will be shown when running rush info yourpackage.
- An executable script named undo (optional) - this will be executed when running rush undo yourpackage.
In the main and undo scripts, you have the following environment variables available to you:
- $REPO - name of the rush repo
- $REPO_PATH - path of the rush repo
- $USER_CWD - the directory from which rush was executed
- $VERBOSE - if the user passed --verbose
- $FORCE - if the user passed --force
Note that the main and undo scripts are executed in the same folder they live in, so you can copy files from the package's directory to wherever they need to be.
If you need to read/write files in the user's current direcotory, use the $USER_CWD environment variable.
The main and undo scripts can be written in any language, as long as they have a shebang line.

Using with GitHub Actions

Rush can be very useful for running remote shell scripts as part of your GitHub Actions workflow. This sample configuration shows how to install rush and connect to your rush repository from a GitHub Actions workflow.

# .github/workflows/main.yml
name: Test
on: [push]

jobs:
  main:
    name: Rush demo
    runs-on: ubuntu-latest

    steps:
    - name: Install rush
      run: curl -Ls http://get.dannyb.co/rush/setup | bash

    # Replace with your own repository
    - name: Connect to rush repository
      run: rush clone dannyben/rush-repo-template --default --shallow

    - name: Run a sample script from the repo
      run: rush get hello

Uninstalling

$ curl -Ls get.dannyb.co/rush/uninstall | bash

Contributing / Support

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.

DannyBen / rush-cli