\n\n## About\n\nUnshackle is a small release scripting [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for JavaScript projects. If releasing new versions of your JavaScript application involves running the same dozens of Git commands, intermixed with various CLI tools and manual by-a-human steps, it might be for you. In particular, unshackle aims to provide a simple language for combining a series of shell, human, and arbitrary JavaScript tasks.\n\n## Installation\n\n```bash\nnpm install unshackle\n```\n\n## Usage\n\nTypical usage involves writing a script for your release that loads the unshackle\npackage and uses it to execute a series of steps.\n\nYou can execute your script and view its output in the console. Prompts will\npause and wait for your input.\n\nFor now, you must run your script from the working directory that any shell\ncommands should start in.\n\n```javascript\n#!/usr/bin/env node\n\nconst unshackle = require('unshackle')\n\n// Create a bucket for remembering state throughout the run.\nconst state = {}\n\nunshackle\n.start('You are starting an example release. Good luck.')\n// Print does what you expect.\n.print('First on the agenda, listing files with ls.')\n\n// Run executes string commands in a shell.\n.run('ls')\n\n// Prompts pause for user input.\n.prompt('What is your favorite letter?', ['a', 'b', 'c'])\n\n// JavaScript steps are functions that accept the output of preceding steps as\n// input.\n.run(letter => console.log(`Proceeding with a release for the letter ${letter}.`))\n\n// JavaScript steps can return a promise to perform asynchronous tasks.\n.run(() => {\n console.log('Crunching numbers, or something...')\n return new Promise (resolve => setTimeout(resolve, 3000))\n})\n\n// Use state to remember user input.\n.prompt('What is your favorite letter now?', ['a', 'b', 'c'])\n\n// Define a labeled mark in the process.\n.run('trap-state', letter => state.letter = letter)\n\n// Use the unshackle runner in a custom step, making sure to return the promise\n// property, to block.\n.run(() => unshackle.prompt(`Please manually confirm your appreciation for the letter ${state.letter}.`).promise)\n\n// Use fail to abort and exit if something goes wrong.\n.run(() => {\n if (Math.random() < .1) {\n unshackle.fail('Today is not a good day.')\n }\n})\n\n// Exit the entire process, with a message.\n.done('Thanks! This release has been a success.')\n```\n\n### Relocating your release script\n\nIf you want to edit a release script that is in source control, you might want\nto make a copy of it outside of your project. For example, if changes were to\nmake your Git working directory dirty, for example, it could interfere with\ncertain Git commands you might have in your release script.\n\n### Marks\n\nSteps have an optional first argument for defining a mark. Marks are useful in\nthat they create readable labels in the output of your release, and they give\nyou a way to restart failed or incomplete releases at a certain step.\n\nYou can start from a mark by passing it as a second argument to\n`unshackle.start`. Starting from a mark skips all steps before that mark, with\nsome exceptions. There may be steps that occur before the mark that are\nrequired to run, usually those that prompt the user for information, as no\ninformation is saved between executions of your release script. You can\nforce such a step to always run, and prompts always run by default.\n\n```javascript\nconst state = {}\n\nunshackle\n// An optional step to print a message. It can also be used to specify a mark.\n.start('Starting a release', 'deploy')\n\n// This step is skipped, because it is before the \"deploy\" mark.\n.run('echo \"You should not be reading this\"')\n\n// At this point in time, prompts are never skipped and will always run.\n.prompt('What type of release is this?', ['major', 'minor', 'patch'])\n\n// The true parameter forces this step to run, even when starting from the\n// \"deploy\" mark\n.run(type => state.type = type, true)\n\n// This step has the \"deploy\" mark, so when used, all steps from here on will\n// run.\n.run('deploy', () => {\n deployVersion(state.type)\n})\n\n// This prints a message and exits the entire process.\n.done('Deployment complete')\n```\n","readmeFilename":"README.md"}
![\"unshackle\"](\"https://cloud.githubusercontent.com/assets/1095217/19737639/cf70c50c-9b79-11e6-8d46-8d469c7c3b76.png\")
\n![\"Travis](\"https://travis-ci.org/bazaarvoice/unshackle.svg?branch=master\")
\n \n