DOCSEARCHbyAlgolia
Submit Docs

gws Workspace Manager

repository·master·Indexed 42 days ago

https://github.com/streakycobra/gws

A lightweight, Bash-based helper for managing workspaces composed of multiple Git repositories. gws allows users to define workspace structures via a .projects.gws configuration file, sync repositories across machines, and monitor the status of all projects simultaneously. It includes features for automatic repository detection, local project filtering via .ignore.gws, and customizable color themes.

Tokens
1.3K
Snippets
4
Records
6
Agent score
4%

What's inside gws

  1. Quick Start with gws

    master

    To start managing your workspace with gws, follow these steps:

    1. Initialize your workspace

    Option A: Manual Configuration Create a .projects.gws file in your workspace folder (e.g., ~/dev) and define your projects using the syntax described in the Syntaxes section.

    Example .projects.gws content:

    # Work related
work/tools/q | https://github.com/harelba/q.git

# Other
contrib/gws  | https://github.com/StreakyCobra/gws.git
contrib/peru | https://github.com/buildinspace/peru

    Option B: Automatic Detection Navigate to your workspace folder and run gws init. This will detect existing Git repositories and generate the .projects.gws file for you.

    2. Sync and Manage Repositories

    • Clone missing repos: Run gws update to clone all repositories listed in .projects.gws that are not yet present on your system. To clone only specific ones, use gws clone <path>.
    • Check status: Run gws or gws status to see which repositories are clean, have uncommitted changes, or are out-of-sync with origin.
    cd path/to/your/workspace
gws init
gws update

  2. Install gws

    master

    Requirements

    • git
    • bash > 4.0

    Installation by Platform

    Arch Linux

    Install the gws package from the AUR.

    openSUSE

    Install the gws package from the devel:tools repository.

    macOS

    1. Upgrade bash to version > 4.0 using brew install bash.
    2. Note for macOS users: Because gws uses GNU-specific sed and cut options, you may need to install coreutils and gnu-sed via Homebrew and use an alias to ensure the correct binaries are used:
    brew install gnu-sed coreutils
alias gws="PATH=/usr/local/opt/coreutils/libexec/gnubin:usr/local/opt/gnu-sed/libexec/gnubin:$PATH gws"

    Other Linux Distributions

    Ensure the src/gws bash script is in your $PATH. You can:

    • Place it in /bin (requires root).
    • Place it in ~/.local/bin and ensure that directory is in your $PATH by adding export PATH="$PATH:/path/to/scripts/dir" to your ~/.bashrc.
    brew install gnu-sed coreutils
alias gws="PATH=/usr/local/opt/coreutils/libexec/gnubin:usr/local/opt/gnu-sed/libexec/gnubin:$PATH gws"

  3. Configure the .projects.gws file

    master

    The .projects.gws file defines the projects in your workspace. One project per line.

    Syntax: <any/folder/path> | <remote_url1> <remote_name1> [ | <remote_url2> <remote_name2> [ | ... ]]

    Rules:

    • <remote_name1> can be omitted; if omitted, origin is used.
    • <remote_name2> can be omitted; if omitted, upstream is used.
    • There must be at least one remote mapping to origin.
    • The folder path can be any valid Linux path that does not contain |, #, or spaces.
    • Remote names must not contain |, #, or spaces.
    • Remote URLs must not contain |, #, or spaces.
    • Blank lines and comments (starting with #) are supported.
    work/theSoftware | git@github.com:You/theSoftware.git
perso/gws        | git@github.com:You/gws.git         | git@github.com:StreakyCobra/gws.git

  4. Use .ignore.gws to filter projects

    master

    The .ignore.gws file allows you to locally disable specific projects from the .projects.gws list using regular expressions. This is useful for keeping a single .projects.gws file synced across multiple machines while ignoring work-related projects on a home computer.

    Syntax: One regular expression per line. The regex is matched against each project's folder path.

    Examples:

    • Ignore the work folder and all subfolders: ^work/
    • Ignore all repositories ending with -work: -work$
    • Ignore any repository containing the letter a: a
    ^work/

  5. Customize the gws color theme

    master

    You can customize the color scheme by providing a shell script that redefines the color codes C_*. gws will source this file if it finds it at one of the following locations (in order of precedence):

    1. ./.git/theme.gws (inside the workspace git directory)
    2. ${HOME}/.theme.gws
    3. ${HOME}/.config/gws/theme

    Security Note: Themes are not loaded from the project directory (where .projects.gws lives) to prevent executing arbitrary shell code pulled from a remote Git repository.

  6. Reference: gws CLI commands

    master

    The following commands are available to manage your workspace:

    • gws or gws status: Shows the status of all repositories (clean, uncommitted changes, or out-of-sync with origin).
    • gws init: Detects existing repositories and creates the .projects.gws file.
    • gws update: Clones all missing repositories from the .projects.gws list.
    • gws clone <path>: Clones a specific missing repository from the list.
    • gws fetch: Fetches modifications from origin for all repositories.
    • gws ff: Performs a fast-forward merge (pull) from origin for all repositories.
    • gws check: Scans the workspace to check for known, unknown, ignored, and missing repositories. (Note: This can be slow in large directories).

    Global Option:

    • --only-changes: When used with update, status, fetch, or ff, this option hides repositories that are unaffected by the operation (e.g., repos that are already clean or have no remote changes).