@steeringwaves/gobs

gobs

Parallel project runner with built in git integrations using user defined configuration files.

Why does this exist? I work on a lot of different git repos at the same time and and got tired of having so many terminal windows open to checkout branches, fetch, clone, run common scripts, etc... Hence the name gobs

use cases

• Keeping up to date git repos with a single command
• Creating/Checking out a common git branch across several repos
• Seeing what changes existing across several git repos
• Running commands across several folders

roadmap

• Specify configuration file via arugment --config
• Specify configuration file via environment varialbe GOBS_CONFIG
• Automatically search for configuration file recurisvely upwards looking for a file named .gobs.yml
• Allow multi-root configurations
• Allow filtering by groups --group eg "test" or even `"test || (home && 3dprinting)"
• Allow filtering by out project(s) by name --without
• Allow specifying a single project by name --project
• Allow run to run command that is present in all projects
• Allow foreach <command> to run a specified shell command in all projects
• Configuration templating with handlebars
• Parallel execution option (right now it's on by default with --no-parallel)
• Specify projects that have no git repo
• Specify batches (directed graphs) that execute multiple commands across multiple projects using a directed graph to take full advantage to parallel processing (users can specify upstream or downstream steps)
• Optionally render batches to terminal for debugging
• Should we make the parallel execution option off by default and just use -j like make?
• Allow overrides for uses that are always used from .gobs/config.yml (no color, global variables, etc...)
• describe should generate a manifest of all projects and include the current commit hash, if any files have changed and optionally any tags
• describe manifest should include an optional last log message
• Integration tests using docker
• Allow vars to be specified on the command line, which is super useful for things like (armv7l, x86_64, armhf etc...)
• Auto generate vscode workspaces with one or more groups, and allow a workspace template to be specified
• What if someone points more than one project at a path? Should be detect this somehow?
• Tab completion will be tricky since a configuration path must be specified (possible if they use an env variable though)
• Allow digraph commands to point to another file that defines them (include paths could be weird)
• Allow project definitions to point to another file that defines them (include paths could be weird)
• Allow option parsing via env variables (especially for specifying the configuration file)
• Allow git project to specify a default branch name to checkout initially (eg legacy/next etc...)

things not on the roadmap

• Support for every possible version of git (maybe we could get at least check the current version and see if it's > some version?)
• Replacing build systems like make - if you want to run a few commands that's fine but ideally this tool just calls make or insert build tool here

commands

string

string renders the configuration to either yaml/json for use with other applications

issues

• Groups don't make sense for digraph commands
• We have a keyword for a group named all so this would prevent a user from using a group named this, also our templates allow linking to projects but that syntax uses * instead. Using * on the command line is a pain because you have to specify it as '*' or else shell expansion will bite you
• Templating commands that are run on the shell will break if you try to specify a shell variable such as "cd ${HOME} && pwd" however "cd $HOME && pwd" or "cd \"${env.HOME}\" && pwd" or home=$(echo $HOME) && cd $home && pwd will be fine
• This shells out to run commands - there could be some strange quote escaping going on preventing some commands from working
• Windows/Mac is completely untested

digraph (directed graph) logic when running commands

• Specify if a project is upstream/downstream
• Digraph steps must have unique id's to prevent the vertices from looping
• Digraph steps must point to a valid project name
• Digraph steps can call out one or more project defined commands as well as one or more exec shell commands

templating configs

Using eval is a pretty nasty hack, but allows for some nifty dynamic configurations using env variables.

Here is a snipped showing how the eval is executed:

eval("function run(self, app, env, vars){return `" + str + "`;} run(compileWith.self, compileWith.app, compileWith.env, compileWith.vars)")

• ${env.HOME}
• ${app.config_dir} the directory of the specified configuration file
• ${self.name} only valid inside a project but self refers to the current project value

add more details on internal variables...

templates

Templates use the handlebars syntax and NOT the eval syntax. I know this may be confusing...

Templates can point to all projects using the keyword '*', but they can also point to an array of projects

Templates also get passed

• env
• app
• self
• projects
• project (assuming this template points to one or more projects)

Example:

templates:
- name: active
  file: "${app.config_dir}/workspace.hbs"
  dest: "${vars.personal_workspace}/active.code-workspace"
  chmod: "0644"
  tools:
    paths:
      clangd: /usr/bin/clangd
      node: "${vars.home_path}/.local/bin/node"
- name: gotidy
  file: "${app.config_dir}/tidy.hbs"
  # don't do this for our example
  # dest: "${project.path}/tidy.sh"
  chmod: "0755"
  projects: "*"
  example_dest: "${project.path}/tidy.sh"

integration tests

• Use docker-compose to perform a real world test spin up a container hosting a git server and another running gobs
• Verify repos can be cloned if they don't exist
• Verify new branches can be created/pushed
• Verify changes can be commited
• Verify changes can be detected
• Verify tags can be pushed
• Verify describe produces the correct output
• Verify branch can be checked out by name/hash/tag/tag regex

changes

• command should be more structured eg {name:..., exec:...}