Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/specht/ag

Ag - issue tracking intertwined with Git
https://github.com/specht/ag

Last synced: about 1 year ago
JSON representation

Ag - issue tracking intertwined with Git

Awesome Lists containing this project

README 

          
h1. Ag - issue tracking intertwined with Git



Ag is an issue tracker built on top of Git. Sound familiar? You bet. Here's the motivation for Ag:



Previously, I would have my code in a Git repository and my issues in a web-based issue tracking system. Put feature ideas and bug reports in the issue tracker, modify the code and resolve issues over time. From the issue tracker's point of view, issues are marked as resolved after some time, but there's no code or commits connected to it. Wouldn't it be useful to see which commits have been made to implement a feature or to resolve a bug?



Too bad it's laborious to connect issues and commits this way - if there was such a connection, we would be able to tell not only who has changed the code and when, but we'd also be able to tell _why_ the code has been changed (and not by means of reading commit messages, but using properly categorized issues from the issue tracker). Commits could be easily (and automatically) categorized into _feature_ or _bug_, for example, or into various other aspects of the software project.



Here are some key points of Ag:



* *Issues are completely managed via Git.* Issues are plain text files which live in a branch separate from the project's source code. This means that as you code, all issues and related  information is right there beside you. And the entire issue history.



* Keeping *issues in a separate Git branch* doesn't spill issue-related information into your code  tree.



* *No more 'um... fixed this and that' commit messages.* When you work with issues, you have  already specified your intentions behind every issue, possibly aided by nested categories. When you tell Ag that you're starting to work on an issue, Ag creates a dedicated topic branch and it will automatically prepare the commit message to establish the connection between a commit and an issue. Feel free to add comments if your commit needs more explaining.



* *Nested categories.* Issues can be viewed from different perspectives. Typically, an issue is related to various aspects of technical, conceptual, or organizational levels. Such multi-perspective arrangements can be captured by Ag using nested categories (all categories are arranged in a tree). Issues can be connected to one or more categories.



* *Smart tab auto-completion* on the command line interface. 



h2. Installation



There's an installation package for Debian-based Linux systems:



bc. $ sudo add-apt-repository ppa:micha-specht/ag

$ sudo apt-get update

$ sudo apt-get install ag



Restart your shell, and that should be it. Try @ag help@ to get started.



h2. Tutorial



You need a Git repository to get started. 



h3. Creating and viewing issues



Let's start using Ag by creating an issue:



bc. $ ag new



Ag will launch a text editor with a file which says:



bc. Summary:

Priority: 5



Enter the issue's summary and enter some more details if you like:



bc.. Summary: Colors are all wrong

Priority: 5



When you try to set the foreground color to red, it becomes yellow. How's that even possible?



p. If you like, adjust the priority: 0 for lowest, 9 for highest. Save the file and exit the editor. Ag will respond with:



bc. Added issue: tz9540-colors-are-all-wrong



The small bit in front is the issue ID. You can use it to specify the issue (although it should be something different for you).



bc. $ ag list 

[tz9540]+5   Colors are all wrong



Yes, the issue is still there! The @+5@ bit reports the priority of the issue, and if there were more issues, they would be sorted by that value. Let's look at the issue in detail:



bc.. $ ag show tz9540

═══════════════════════════════

[tz9540]+5 Colors are all wrong

═══════════════════════════════

Created: Wed Nov 19, 2014 by Michael Specht

Updated: Wed Nov 19, 2014 by Michael Specht

Priority: 5

───────────────────────────────

When you try to set the foreground color to red, it becomes yellow. How's that even possible?



h3. Where does Ag store its data?



Ag creates a new branch @_ag@ in your Git repository:



bc. $ git branch 

  _ag

* master



Let's have look:



bc.. $ git checkout _ag

Switched to branch '_ag'



$ ls

issue



$ ls issue/

tz9540



$ cat issue/tz9540

Summary: Colors are all wrong

Priority: 5



When you try to set the foreground color to red, it becomes yellow. How's that even possible?



p. That's all there is to it. Nothing to see here! Let's switch back to the master branch:



bc. $ git checkout master

Switched to branch 'master'



h3. Tab auto-completion



When you specify issues, only the first six characters are taken into account. For example, issue @tz9540@ may be specified as @tz9540@, @tz9540-colors-are-all-wrong@, or @tz9540-gosh-dang-it-to-heck@. The summary is usually just there to help you recognize the issue, but it may change if you modify the issue's summary. The ID remains fixed, however.



While these IDs are really handy to refer to an issue, they're hard to memorize and type. So here's the good news: You can use tab completion for this! To specify issue @tz9540-colors-are-all-wrong@ on the command line, you can type any of the following:



* @tz[TAB]@

* @color[TAB]@

* @wrong[TAB]@



...or even shorter pieces. Yes, these are words from your summary. Ag will expand your input to the issue ID followed by the summary, like this:



bc. $ ag sh[TAB] co[TAB]



...will be turned into this:



bc. $ ag show tz9540-colors-are-all-wrong 



h3. Categories



Let's add another issue:



bc. $ ag new



bc.. Summary: Implement XML export 

Priority: 5



We need some way to export everything to XML because you know, ENTERPRISE!



bc. Added issue: br9077-implement-xml-export



p. Now it's time to connect our issues to some categories. In this case, we already have two types of issues - features and bugs, so let's create categories for them:



bc. $ ag cat new



bc. Summary: Issue type



bc. Created new category: ko4993-issue-type

# This is the parent category which will have 'feature' and 'bug' as its children.



bc. $ ag cat new ko4993-issue-type

# We can already specify on the CLI that this category should be a child of 'Issue type', 

# but it could as well be done later using 'ag cat reparent'



bc. Summary: Feature

Parent: ko4993-issue-type



bc. Created new category: hc6100-feature



bc. $ ag cat new ko4993-issue-type



bc. Summary: Bug

Parent: ko4993-issue-type



bc. Created new category: eo6845-bug



Good. Let's look at our categories:



bc. $ ag cat list 

[ko4993] Issue type

[eo6845] ├──Bug

[hc6100] └──Feature



h3. Connect issues to categories



Now we can connect issues to categories:



bc. $ ag list

[br9077]+5   Implement XML export

[tz9540]+5   Colors are all wrong



'Implement XML export' is a feature, so let's record that:



bc. $ ag connect xml[TAB] feat[TAB]

# this will turn into: ag connect br9077-implement-xml-export hc6100-feature



bc. Connected issue br9077-implement-xml-export to 1 category



'Colors are all wrong' is a bug, so let's record that, too:



bc. $ ag connect col[TAB] bug[TAB]

# this will turn into: ag connect tz9540-colors-are-all-wrong eo6845-bug



bc. Connected issue br9077-implement-xml-export to 1 category



Now the issues are connected to the categories:



bc. $ ag list

[br9077]+5   Implement XML export (Feature)

[tz9540]+5   Colors are all wrong (Bug)



Want to see which bugs are there?



bc. $ ag list bug[TAB]

# this will turn into: ag list eo6845-bug



This gives you all issues which are connected to the 'Bug' category:



bc. [tz9540]+5   Colors are all wrong (Bug)



As you've seen, categories are arranged in a tree (each category item has a parent, which can be null). Categories are expected to be pretty stable during a project. Issues can be connected to zero, one, or more categories and they're not directly related to each other, they may only share common categories.



h3. Can we start working on an issue already?



Alright, let's fix that strange color bug:



bc. $ ag start col[TAB]

# this will turn into: ag start tz9540-colors-are-all-wrong



bc. Switched to a new branch 'tz9540-colors-are-all-wrong'



Now you've got your own topic branch to deal with that bug. Make some edits, test your code, and commit:



bc. git commit



And the commit message is already there:



bc.. [tz9540]+5 Colors are all wrong



# Please enter the commit message for your changes. Lines starting

# with '#' will be ignored, and an empty message aborts the commit.

# On branch tz9540-colors-are-all-wrong

# Changes to be committed:

#   (use "git reset HEAD ..." to unstage)

#

#       modified:   hello.txt

#



p. The issue is referenced from the commit via @[tz9540]@. How does Ag know we're working on that bug? It's not being explicitly recorded anywhere. Ag looks at the branch name. If it starts with two letters and four digits, followed by a dash, it must be an issue! Now let's have a look at the issues again:



bc. $ ag list 

[br9077]+5 ⇢ Implement XML export (Feature)

[tz9540]+5 ⇒ Colors are all wrong (Bug)



The arrows indicate that there has already work been done for this issue, that is, there is at least one commit which references the issue. The double arrow (⇒) indicates that there are commits reachable from your current branch, and the dashed arrow (⇢) indicates that there are commits in other branches.



If you don't want to populate your Git repository with all kinds of branches and just want to do a quick commit, you can use the following shortcut:



bc. $ ag commit col[TAB] 



This will perform a git commit as if you were in the specified topic branch, passing along all following arguments.



h3. Resolving issues



Now that we have fixed the color bug, we can resolve the issue. Because this is all happening in Git, let's remove that bug (we'll still be able to walk back in history to dig out the bug and see when it was filed, when commits have been made, and when it was removed):



bc. $ ag rm col[TAB]

Removing issue: [tz9540]+5 Colors are all wrong

Are you sure you want to remove this issue [y/N]? 



Type 'y' and the issue won't show up in listings or tab completions anymore. Don't worry though, it's not gone at all. You can still say @ag start tz9540@ and you'll be given a topic branch and when you commit, you still get the automatically prepared commit message. We know it was around in the past, but we don't want to see it anymore because we're done with it.



h3. Wrap up



Now you should be able to create issues and categories. Use @ag help@ to learn more about other commands. Once you've set up some categories, you can already specify them on the command line when you create an issue. For example, to file a new bug:



bc. $ ag new bug[TAB]



The newly created issue will be connected to @eo6845-bug@.



Oh, here's what you get when you type @ag help@:



bc.. Ag - issue tracking intertwined with Git



Usage: ag  []



Available category-related commands:

cat new       Create a new category

cat list      List all categories

cat show      Show raw category information

cat edit      Edit a new category

cat reparent  Re-define the parent category of a category

cat rm        Remove a category



Available issue-related commands:

new           Create a new issue

list          List all issues

show          Show raw issue information

oneline       Show condensed issue information in a single line

edit          Edit an issue

connect       Connect an issue to a category

disconnect    Disconnect an issue from a category

start         Start working on an issue

locate        Find commits and corresponding branches for an issue

rm            Remove an issue

restore       Restore a previously removed issue

commit        Commit using an issue, regardless of the current branch



Miscellaneous commands:

pull          Pull upstream changes

push          Push changes upstream

search        Search for categories or issues

log           Show of a log of Ag activities

visualize     Launch a web browser and visualize commits

help          Show usage information



See 'ag help ' for more information on a specific command.

Ag supports tab completion pretty well - try to specify category or 

issue IDs via keywords, they will be auto-completed.



h2. To do



* there should be a way to restore a previously deleted issue or category

* search results should be more clear (right now, you find removed issues but you can't tell 

  from the search results that they have been deleted)

* web interface and reporting (oh, the possibilities!)