When using project-tracking tools such as Jira, it can be useful to include a story tag (such as EG-123) in commit messages, so that changes can be linked to stories and vice versa.
Instead of doing so manually, which can be prone to inconsistency and mistakes, this tool automates the process by rewriting commit messages to include the current story.
Install through npm:
$ npm install -g storymanIn order to rewrite commit messages automatically, storyman will need to be installed in any Git repositories where you want tagged commits.
This can be achieved by running story install inside an existing Git repository:
$ cd ~/projects/some-project
$ story install
Created prepare-commit-msg hook for /home/shea/projects/some-project.Or by passing a repository to story install as the first argument:
$ story install ~/projects/another-project
Created prepare-commit-msg hook for /home/shea/projects/another-project.storyman v2 has switched to a branch-based method of tracking stories. When working on a new story, create a Git branch beginning with the story tag:
$ git checkout -b SM-124Branch names can include an optional 'comment' following this story tag, which will be ignored by storyman:
$ git branch -m SM-124-introduce-x-featureYou check what the detected story is using story:
$ story
EG-123When making a commit, storyman will automatically add the current story tag to the beginning of the commit message:
$ git commit -m "Made some changes."
[EG-123 fb98b25] EG-123 Made some changes.
1 file changed, 71 insertions(+), 3 deletions(-)If you're commiting to a branch that does not begin with a story tag, such as main, storyman will notice and prompt
if you would like to add one to the commit message anyway:
$ git commit -m "Made some changes."
✔ [storyman] Commiting to a non-story branch. Enter a story to tag this commit, or
leave blank to commit untagged: EG-123
[main fb98b25] EG-123 Made some changes.
1 file changed, 71 insertions(+), 3 deletions(-)storyman has the ability to connect to your Jira instance to fetch information about the current story. This can be
initiated by running story info, where you will need to provide the Jira site URL and an API token.
Once this has been initialised, storyman will also validate the current story when making commits. If the story is marked as resolved in Jira, a warning will be shown, and you will be prompted to confirm that you wish to proceed with the commit:
$ git commit -m "Made some changes."
⚠ [storyman] Warning: EG-123 is resolved as 'Done'. Continue with this commit? (Y/n)Storyman also supports workflows that involve also including the name of the commit authors in each message, like this:
EG-12 Made some changes. [Shea]
To enable this functionality, set the defaultAuthor configuration property:
$ story config set defaultAuthor SheaIf you specify an author in the commit message manually, storyman will attempt to detect this and refrain from adding an author tag.
Storyman makes it easy to navigate from code to the Jira ticket you're currently working on.
Running the story open command will open the Jira ticket for the current story in the default web browser.
The first time you run this, it will prompt to enter a Jira site URL. This can be a URL to Jira cloud or to a self-hosted instance:
$ story open
What is your Jira site URL?: https://something.atlassian.net/
Opening https://something.atlassian.net/browse/EG-12story configstory config clear PROPstory config liststory config set PROP VALUEstory config unset PROPstory getstory help [COMMAND]story info [STORY]story install [REPO]story jira [STORY]story liststory open [STORY]story uninstall [REPO]
Display the list of current configuration properties.
USAGE
$ story config
DESCRIPTION
Display the list of current configuration properties.
ALIASES
$ story config list
EXAMPLES
$ story config
Reading configuration from file:///home/shea/.storyman.json
defaultAuthor = "Shea"
jiraUrl = "https://something.atlassian.net/"
See code: src/commands/config/index.ts
Reset a configuration property to its default value.
USAGE
$ story config clear PROP
DESCRIPTION
Reset a configuration property to its default value.
ALIASES
$ story config clear
EXAMPLES
$ story config unset defaultAuthor
Display the list of current configuration properties.
USAGE
$ story config list
DESCRIPTION
Display the list of current configuration properties.
ALIASES
$ story config list
EXAMPLES
$ story config
Reading configuration from file:///home/shea/.storyman.json
defaultAuthor = "Shea"
jiraUrl = "https://something.atlassian.net/"
Set a new value for a configuration property.
USAGE
$ story config set PROP... VALUE...
DESCRIPTION
Set a new value for a configuration property.
EXAMPLES
$ story config set defaultAuthor Shea B
defaultAuthor = Shea B
See code: src/commands/config/set.ts
Reset a configuration property to its default value.
USAGE
$ story config unset PROP
DESCRIPTION
Reset a configuration property to its default value.
ALIASES
$ story config clear
EXAMPLES
$ story config unset defaultAuthor
See code: src/commands/config/unset.ts
Retrieve the story identifier from the current Git branch.
USAGE
$ story get
DESCRIPTION
Retrieve the story identifier from the current Git branch.
EXAMPLES
$ story
SM-12
See code: src/commands/get.ts
Display help for story.
USAGE
$ story help [COMMAND...] [-n]
ARGUMENTS
[COMMAND...] Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for story.
See code: @oclif/plugin-help
View information about a story.
USAGE
$ story info [STORY]
ARGUMENTS
[STORY] Fetch information for this story, instead of the current story.
DESCRIPTION
View information about a story.
EXAMPLES
$ story info
Current story is SM-123: Example story name.
See code: src/commands/info.ts
Install the git prepare-commit-msg hook.
USAGE
$ story install [REPO] [-f]
ARGUMENTS
[REPO] [default: .] Path to Git repository. Defaults to current directory.
FLAGS
-f, --force override an existing prepare-commit-msg hook
DESCRIPTION
Install the git prepare-commit-msg hook.
Install the git `prepare-commit-msg` hook.
EXAMPLES
$ story install
Created prepare-commit-msg hook for /home/shea/projects/some-project.
$ story install ~/projects/another-project
Created prepare-commit-msg hook for /home/shea/projects/another-project.
See code: src/commands/install.ts
Open the active story in Jira.
USAGE
$ story jira [STORY]
ARGUMENTS
[STORY] Open this story, instead of the current story.
DESCRIPTION
Open the active story in Jira.
ALIASES
$ story jira
EXAMPLES
$ story open
Opening https://something.atlassian.net/browse/SM-12
$ story open 42
Opening https://something.atlassian.net/browse/SM-42
$ story open TS-19
Opening https://something.atlassian.net/browse/TS-19
List stories assigned to the current Jira user.
USAGE
$ story list
DESCRIPTION
List stories assigned to the current Jira user.
See code: src/commands/list.ts
Open the active story in Jira.
USAGE
$ story open [STORY]
ARGUMENTS
[STORY] Open this story, instead of the current story.
DESCRIPTION
Open the active story in Jira.
ALIASES
$ story jira
EXAMPLES
$ story open
Opening https://something.atlassian.net/browse/SM-12
$ story open 42
Opening https://something.atlassian.net/browse/SM-42
$ story open TS-19
Opening https://something.atlassian.net/browse/TS-19
See code: src/commands/open.ts
Uninstall the git prepare-commit-msg hook.
USAGE
$ story uninstall [REPO]
ARGUMENTS
[REPO] [default: .] Path to Git repository. Defaults to current directory.
DESCRIPTION
Uninstall the git prepare-commit-msg hook.
Uninstall the git `prepare-commit-msg` hook.
EXAMPLES
$ story uninstall
Removed prepare-commit-msg hook from /home/shea/projects/some-project.
$ story uninstall ~/projects/another-project
Removed prepare-commit-msg hook from /home/shea/projects/another-project.
See code: src/commands/uninstall.ts