@vpet95/git-sc v1.0.3

✨ git-sc ✨ is a tool to help you quickly and easily generate git branches from Shortcut stories.

Installation

Use the npm package manager to install git-sc globally:

npm install -g @vpet95/git-sc

Alternatively, you can run git-sc directly via npx.

Prerequisites

git-sc requires a Shortcut API token to run - please read the official help article on generating your own Shortcut API token for more info.

Optionally, you may acquire a Twinworld topic tagging API token as well as a RapidAPI host name. At the time of this writing the free tier of the API will allow for 10k calls per month, which is more than sufficient for git-sc. The tool will still work without topic tagging, but may produce less sophisticated branch names using a simpler algorithm.

Usage

At minimum, git-sc must be run with a Shortcut story id:

git-sc <story-id>

The tool will assume all default settings and attempt to create a new git branch within your current directory. git-sc is also configurable via command-line arguments, JSON configuration file, and/or environment variables.

Configuration

Command-line

Calling git-sc with --help will produce a list of command-line options:

Options:
  -V, --version                                output the version number
  -d, --git-dir <path>                         path to the git repository. If omitted, current directory is used
  -p, --parent <branch>                        the parent branch to use. **Note: this tool assumes your local and remote branches have identical names.
  -u, --update                                 update the parent branch before creating the new branch
  -pr, --parent-remote <parent branch remote>  the name of the git remote to use when updating the parent branch.
  -cr, --child-remote <child branch remote>    the name of the git remote to use when creating and linking to the remote of you newly created branch. If omitted, uses the parent remote
  -bp, --branch-prefix <prefix>                a prefix to give the branch name prior to the shortcut ticket number.
  -o, --overwrite                              overwrite local branch if it already exists. NOTICE: this will discard any working changes you have
  -l, --limit <count>                          Limits the number of words in the resulting branch name. If omitted, or zero, all unfiltered words are included.
  --debug                                      Determines whether git-sc outputs status and debug messages to the console
  --twinword-api <token>                       Your twinword API key. To generate one, go to https://rapidapi.com/twinword/api/topic-tagging/ and make a free account. If omitted, a simpler name filtering algorithm
                                               is used. git-sc will also look at the RAPID_HOST environment variable.
  --rapidapi-host <URL>                        Your RapidAPI Host name. To generate one, go to https://rapidapi.com/twinword/api/topic-tagging/ and make a free account. If omitted, a simpler name filtering
                                               algorithm is used. git-sc will also look for the TWINWORD_TOKEN environment variable.
  --shortcut-api <token>                       Your Shortcut API token. This parameter is required. git-sc will also look for the SC_TOKEN environment variable
  -c, --config                                 Path to a configuration JSON file containing git-sc options
  -h, --help                                   display help for command

Configuration JSON

Alternatively, git-sc can be configured with a JSON file of the following format:

{
  "gitDir": "<relative or full path>",
  "parent": "<git branch name",
  "parentRemote": "<parent branch's remote name>",
  "childRemote": "<child branch's remote name>,
  "update": true,
  "branchPrefix": "<prefix>",
  "overwrite": false,
  "twinwordApi": "<API token>",
  "rapidapiHost": "<URL>",
  "shortcutApi": "<API token>",
  "limit": 0
}

The configuration file is specified via the --config option. The file can be given any name. If omitted, git-sc will look for a configuration file in the current directory by the name gitscconf.json.

Environment Variables

git-sc supports the following environment variables:

• SC_TOKEN: specifies the Shortcut API key

• TWINWORD_TOKEN: specifies the Twinword topic tagging API key

• RAPID_HOST: specifies the RapidAPI host URL

Output

Branch names generated by git-sc follow the format:

<prefix><story id>/<story title keywords>

There is no way to configure this at the time, but is a planned feature.

Roadmap

Some planned updates include:

• Unit tests
• More debug output
• More output name format configurability
• Exposing more Shortcut story fields for name formatting
• Command to easily delete branches based on shortcut story id
• Command to clean up local branch list
• Interactive mode / prompting
• Rewrite git integration to make use of a more robust API
• A validation command to check program settings and/or configuration file

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT