{"id":13702543,"url":"https://github.com/sandstorm/dev-script-runner","last_synced_at":"2025-04-14T21:30:54.809Z","repository":{"id":63911623,"uuid":"571732064","full_name":"sandstorm/dev-script-runner","owner":"sandstorm","description":"Write and document recurring development tasks inside a shell script and run them from anywhere inside your projects folder structure.","archived":false,"fork":false,"pushed_at":"2023-03-01T06:46:10.000Z","size":2586,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-08-03T21:02:30.729Z","etag":null,"topics":["bash","bash-scripting","shell","task-runner","tasks"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandstorm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-11-28T19:13:00.000Z","updated_at":"2024-02-24T18:27:16.000Z","dependencies_parsed_at":"2024-01-14T19:14:40.644Z","dependency_job_id":"c6df5a6f-7133-4edc-84c8-a38829db13d7","html_url":"https://github.com/sandstorm/dev-script-runner","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstorm%2Fdev-script-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstorm%2Fdev-script-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstorm%2Fdev-script-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstorm%2Fdev-script-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandstorm","download_url":"https://codeload.github.com/sandstorm/dev-script-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223644656,"owners_count":17178775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-scripting","shell","task-runner","tasks"],"created_at":"2024-08-02T21:00:37.573Z","updated_at":"2024-11-08T07:17:36.961Z","avatar_url":"https://github.com/sandstorm.png","language":"Go","funding_links":[],"categories":["Practices"],"sub_categories":["Development and Staging"],"readme":"\u003ch1 align=\"center\"\u003eDev Script Runner\u003c/h1\u003e\n\u003cp align=\"center\"\u003eWrite and document recurring development tasks inside a shell script and run them from anywhere inside your projects folder structure.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\n\u003ca style=\"text-decoration: none\" href=\"https://github.com/sandstorm/dev-script-runner/releases\"\u003e\n\u003cimg src=\"https://img.shields.io/github/v/release/sandstorm/dev-script-runner?style=flat-square\" alt=\"Latest Release\"\u003e\n\u003c/a\u003e\n\n\u003ca style=\"text-decoration: none\" href=\"https://opensource.org/licenses/MIT\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"License: MIT\"\u003e\n\u003c/a\u003e\n\n\u003c/p\u003e\n\n----\n\n* [Features](#features)\n* [Motivation](#motivation)\n* [Setup](#setup)\n  * [Writing tasks](#writing-tasks)\n  * [Passing arguments](#passing-arguments)\n  * [Documenting Tasks](#documenting-tasks)\n  * [Structuring tasks into different files](#structuring-tasks-into-different-files)\n* [Usage](#usage)\n* [Roadmap](#roadmap)\n\n----\n\n## Features\n\n* run your development tasks from within a nested folder structure\n* easy initialization of your project\n* autocompletion\n* documentation of your tasks will be used to provide help\n* structure your tasks in different files\n\n## Motivation\n\nWe have recurring tasks in all our projects. Often they require multiple shell commands, e.g. for ...\n\n* setting up a project\n* starting and stopping containers\n* running test\n* ...\n\nThese tasks need to be documented, so why not have them documented in a shell script?\nThis way you can run them without the need of copy and pasting them from a Readme.\n\nWe tried Makefiles, but they are complicated to use. It is also not possible to copy commands \nfrom the Makefile and run them in the shell.\n\nAlways changing back to the root of your project to run a script can be annoying. This is why we want \nto run tasks from inside a nested folder structure.\n\nRunning tasks using the helper should be the same as running tasks directly using the script.\n\nThis is how we ended up with the following API.\n\n`./dev.sh sometask` vs. `dev sometask`\n\nFunctionality only provided by the helper will be uppercase and prefixed with `DSR`.\n\nExample: `dev DSR_INIT` to create the files needed in your project.\n\n## Setup\n\nrun `brew install sandstorm/tap/dev-script-runner` to install\n\nrun `brew upgrade sandstorm/tap/dev-script-runner` to upgrade\n\n**Autocompletion**\n\nrun `dev completion [bash|zsh|fish|powershell] --help` and follow instructions on how to set up autocompletion\n\n\u003e For **MacOS on ARM** the zsh instructions will not work. You have to change your `FPATH` first.\n\u003e\n\u003e ```bash\n\u003e # .zshrc\n\u003e \n\u003e FPATH=\"$(brew --prefix)/share/zsh/site-functions:${FPATH}\"\n\u003e # compinit MUST be called afterwards!\n\u003e autoload -U compinit; compinit\n\u003e ```\n\u003e Now run \n\u003e \n\u003e ```\n\u003e dev completion zsh \u003e $(brew --prefix)/share/zsh/site-functions/_dev\n\u003e ```\n\u003e \n\u003e and restart your terminal.\n\n**Initialization**\n\nIn your project root run `dev DSR_INIT`\n\nThis will create the files needed to start writing your own tasks. Run `dev` and you will see\nexample tasks that have been created for you. You can now start editing your `dev.sh` ;)\n\n### Writing tasks\n\n```bash\nfunction sometask {\n  echo \"TODO: implement sometask\"\n}\n```\n**Tasks starting with `_` are expected to be private and will be ignored**\n\n**You should not use UPPERCASE tasks in your `dev.sh`** as they might be used to provide\nutilities. e.g. `dev DSR_INIT` to init your folder with all the files needed by the \nDev Script Runner\n\n### Passing arguments\n\nYou can run a task providing additional arguments that will be passed to your `dev.sh`\ntransparently. \n\nThe only exception are the `-h` and `--help` flags that are handled by the DevScriptRunner.\nIf you implement them in your `dev.sh` script they will only work if you call your script\ndirectly. `./dev.sh --help` will run your own implementation.\n\n```bash\ndev sometask arg1 arg2 agr3\n```\n\n```bash\nfunction sometask {\n  echo \"$@\" # -\u003e \"arg1 arg2 agr3\"\n  echo \"$1\" # -\u003e \"arg1\"\n  echo \"$2\" # -\u003e \"arg2\"\n  echo \"$3\" # -\u003e \"arg3\"\n}\n```\n\n`$@` can be used for passing all arguments to other tasks in your `dev.sh`.\n\n`$@` MUST always be present at the end of our your `dev.sh` script.\n\n### Documenting Tasks\n\nWe will parse the comment block directly followed by your task, to extract a short description\ndisplayed in the list of tasks and the autocompletion. We will also extract a long description that is\ndisplayed when running `dev sometask --help`\n\n```bash\n# Short description in first line\n#\n# Some more comments giving a detailed description about your task.\n# Your description can span multiple lines. There MUST NOT be any empty lines \n# between the comment block and your task.\nfunction sometask {\n  echo \"TODO: implement\"\n}\n```\n\n### Structuring tasks into different files\n\n```bash\n#!/bin/bash\n############################## DEV_SCRIPT_MARKER ##############################\n\n# You can structure your tasks into different files using `source`. We will also\n# parse these files. The order will be: \n#   1. tasks of the dev.sh\n#   2. tasks of sourced files\nsource ./dev_utilities.sh\nsource ./dev_tasks_testing.sh\nsource ./dev_tasks_release.sh\n```\n\n## Roadmap\n\n* parse from comments: usage, examples, flags, params, ...\n* add ready made tasks or provide copy paste examples\n* CLI test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandstorm%2Fdev-script-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandstorm%2Fdev-script-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandstorm%2Fdev-script-runner/lists"}