A little tool to manage your issues from the CLI, locally and in a distributed way.
how it works (actually figuring out how to do this)
gitbugs is meant to be used from within git repos
when init'd (
gitbugs init), gitbugs will create a new local git repository (it won't touch the original repo history) in
Issues are stored as a markdown
.mdfile, following the
:numis the issue number, and
:titleis the slug of the issue title.
Closed issues are moved from
Related commits can be shown up in the related bug file, or can eventually close the issue. A new comment adds the commit sha1 followed by the commit message. The may use markdown syntax and should adhere to these guidelines.
This is very alpha, gitbugs should be full of bugs. It uses itself to store and track its feature request and (multiple) issues.
gitbugs alone should output the following help.
» gitbugs <command> <options> init Initialize a new git bugs repo, relative $cwd create Create a new issue close Close the given issue list List all open issues view Display issue's id, title, status and content edit Open the default text editor for the given issue hook Enable post-commit hook for the current git repo ls, ll → list new → create info → view
Note that the
gitbugs binary is also alliased as
gb for shorter commands.
init Initializes a new gitbugs repository, tracking the git repository it was created from. If a gitbug repository already exists, the command is a noop.
hook Enables the post-commit hook to catch up specific patterns in commit messages and hook in the issue management.
list Lists all the open issues. Closed issues may be listed using the
gitbugs list closesubcommand (
create Creates a new issue with the given title. The command will prompt for title (default to provided
<title>) and a description. If the description is left blank, the default text editor is used to edit the issue content.
close Closes an issue. Multiple issue id may be provided using a command like
gitbugs close 3 7 15.
view Display informations on an issue, such as the id, title, status and content.
edit Opens the default text editor for the given issue. If the first line heading is changed, the id and/or title are updated accordingly.
This is the very most basic commands gitbugs provides.
The first time any command in
gitbugs is used, it'll check that the
.gitbugs directory is there.
$ gitbugs list Error: Unable to find `./gitbugs`, `gitbugs init` may help Try gitbugs --help
The bug tracking repo needs to be created first.
$ gitbugs init Initialized empty Git repository in /path/to/my/repo/.gitbugs/.git/
gitbugs list is used, it'll show basically nothing cause
there are no open issue to display.
$ gitbugs list # same as gitbugs ls # same as gitbugs ll
To add a new issue, the
gitbugs create Title of the ticket command may
$ gitbugs create Title of the issue » Enter a title for this issue: (Title of the issue) Leave blank to write this in your text editor » Enter a description: Some description, if left the default text editor is used. (vim for posix, notepad for windows) [master (root-commit) 44ab1dd] Some description, if left the default text editor is used. (vim for posix, notepad for windows) 1 files changed, 3 insertions(+), 0 deletions(-) create mode 100644 1-title-of-the-issue.md
It should now be displayed by the
$ gitbugs list ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Id ┃ Title ┃ ┣━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ ┃ #1 ┃ Title of the issue ┃ ┗━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
To show details of a specific ticket,
info) command may help:
$ gitbugs view 1 ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ ┃ id ┃ title ┃ status ┃ ┣━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━┫ ┃ 1 ┃ Title of the issue ┃ open ┃ ┗━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━┛ Some description, if left the default text editor is used. (vim for posix, notepad for windows)
edit command may be handy to tweak the bug file content, either it
is for changing the issue number, its title or body content.
$ gitbugs edit 1
Will launch the default text editor with the raw markdown content. Something like:
## #1 - Title of the issue Some description, if left the default text editor is used. (vim for posix, notepad for windows)
#1 id or
Title of the issue are changed to something else,
the issue number is updated and the file is renamed and comitted
appropriately. If the body content is changed, the file is updated and
committed. In both case, prompts will confirm for file renaming and for
a commit message.
Rename: [Y]es/[N]o (Y) Commit message: Edited issue #1 [master afd662e] Edited issue #1 2 files changed, 6 insertions(+), 2 deletions(-) rename 1-title-of-the-issue.md => 2-new-title-of-the-issue.md (65%)
To close an issue:
$ gitbugs close 1 [master 3e6c855] Close #1 1 files changed, 0 insertions(+), 0 deletions(-) rename 1-title-of-the-issue.md => closed/1-title-of-the-issue.md (100%)
close command is able to take a set of issues' id to lookup and close.
To enable a commit-msg hook in the current repository, the
command may be used.
$ gitbugs hook Initialized post commit hook in /path/to/my/repo/.git/hooks/commit-msg
It'll copy and chmod appropriately the commit-msg hook which may be
bin/commit-msg in this repository.
Original commits happens in the original repository (not gitbugs' one),
this executes the
commit-msg hook. It then uses the package
programmatically to add references to issues or to close them if the
commit messages contain specific patterns like:
git commit -m "Add notes on issue #8" git commit -m "Actually fixing. This closes #8"
GitHub has realy a nice integration of their awesome issue tracker in commit messages.
git commit -am 'Fix things - This relates to #7'
Will add a reference to the given commit directly in the #7 issue thread.
git commit -am 'Fix things for real - This closes #7'
Will automatically close the issue when pushed to the remote repository.
These are just a few examples of the commit semantics regarding issue management.
gitbugs has a built-in post-commit hook you may wish to enable this
kind of functionnality in the original repo gitbugs is tracking.
Currently, the following semantic should be supported:
git commit -m "Commit message with an issue id like #8" git commit -m "Actually fixing. This closes #8"
Not on npm yet (will it be? I dunno!). To install:
git clone git://github.com/mklabs/gitbugs.git cd gitbugs && npm link
Or install globally from the
tar.gz github provides:
npm install https://github.com/mklabs/gitbugs/tarball/master -g
May be run using
which then simply runs
The assertions also happens to be a good place to look at to learn more about API usage, until the documentation is written.