{"id":18423216,"url":"https://github.com/specht/ag","last_synced_at":"2025-04-13T14:44:35.759Z","repository":{"id":15662572,"uuid":"18399992","full_name":"specht/ag","owner":"specht","description":"Ag - issue tracking intertwined with Git","archived":false,"fork":false,"pushed_at":"2017-08-25T08:05:31.000Z","size":705,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-16T07:41:26.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specht.png","metadata":{"files":{"readme":"README.textile","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-03T11:03:02.000Z","updated_at":"2016-05-05T13:42:35.000Z","dependencies_parsed_at":"2022-09-16T19:11:02.099Z","dependency_job_id":null,"html_url":"https://github.com/specht/ag","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specht%2Fag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specht","download_url":"https://codeload.github.com/specht/ag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732119,"owners_count":21152839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T04:36:15.259Z","updated_at":"2025-04-13T14:44:35.725Z","avatar_url":"https://github.com/specht.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"h1. Ag - issue tracking intertwined with Git\n\nAg is an issue tracker built on top of Git. Sound familiar? You bet. Here's the motivation for Ag:\n\nPreviously, 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?\n\nToo 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.\n\nHere are some key points of Ag:\n\n* *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.\n\n* Keeping *issues in a separate Git branch* doesn't spill issue-related information into your code  tree.\n\n* *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.\n\n* *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.\n\n* *Smart tab auto-completion* on the command line interface. \n\nh2. Installation\n\nThere's an installation package for Debian-based Linux systems:\n\nbc. $ sudo add-apt-repository ppa:micha-specht/ag\n$ sudo apt-get update\n$ sudo apt-get install ag\n\nRestart your shell, and that should be it. Try @ag help@ to get started.\n\nh2. Tutorial\n\nYou need a Git repository to get started. \n\nh3. Creating and viewing issues\n\nLet's start using Ag by creating an issue:\n\nbc. $ ag new\n\nAg will launch a text editor with a file which says:\n\nbc. Summary:\nPriority: 5\n\nEnter the issue's summary and enter some more details if you like:\n\nbc.. Summary: Colors are all wrong\nPriority: 5\n\nWhen you try to set the foreground color to red, it becomes yellow. How's that even possible?\n\np. If you like, adjust the priority: 0 for lowest, 9 for highest. Save the file and exit the editor. Ag will respond with:\n\nbc. Added issue: tz9540-colors-are-all-wrong\n\nThe small bit in front is the issue ID. You can use it to specify the issue (although it should be something different for you).\n\nbc. $ ag list \n[tz9540]+5   Colors are all wrong\n\nYes, 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:\n\nbc.. $ ag show tz9540\n═══════════════════════════════\n[tz9540]+5 Colors are all wrong\n═══════════════════════════════\nCreated: Wed Nov 19, 2014 by Michael Specht\nUpdated: Wed Nov 19, 2014 by Michael Specht\nPriority: 5\n───────────────────────────────\nWhen you try to set the foreground color to red, it becomes yellow. How's that even possible?\n\nh3. Where does Ag store its data?\n\nAg creates a new branch @_ag@ in your Git repository:\n\nbc. $ git branch \n  _ag\n* master\n\nLet's have look:\n\nbc.. $ git checkout _ag\nSwitched to branch '_ag'\n\n$ ls\nissue\n\n$ ls issue/\ntz9540\n\n$ cat issue/tz9540\nSummary: Colors are all wrong\nPriority: 5\n\nWhen you try to set the foreground color to red, it becomes yellow. How's that even possible?\n\np. That's all there is to it. Nothing to see here! Let's switch back to the master branch:\n\nbc. $ git checkout master\nSwitched to branch 'master'\n\nh3. Tab auto-completion\n\nWhen 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.\n\nWhile 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:\n\n* @tz[TAB]@\n* @color[TAB]@\n* @wrong[TAB]@\n\n...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:\n\nbc. $ ag sh[TAB] co[TAB]\n\n...will be turned into this:\n\nbc. $ ag show tz9540-colors-are-all-wrong \n\nh3. Categories\n\nLet's add another issue:\n\nbc. $ ag new\n\nbc.. Summary: Implement XML export \nPriority: 5\n\nWe need some way to export everything to XML because you know, ENTERPRISE!\n\nbc. Added issue: br9077-implement-xml-export\n\np. 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:\n\nbc. $ ag cat new\n\nbc. Summary: Issue type\n\nbc. Created new category: ko4993-issue-type\n# This is the parent category which will have 'feature' and 'bug' as its children.\n\nbc. $ ag cat new ko4993-issue-type\n# We can already specify on the CLI that this category should be a child of 'Issue type', \n# but it could as well be done later using 'ag cat reparent'\n\nbc. Summary: Feature\nParent: ko4993-issue-type\n\nbc. Created new category: hc6100-feature\n\nbc. $ ag cat new ko4993-issue-type\n\nbc. Summary: Bug\nParent: ko4993-issue-type\n\nbc. Created new category: eo6845-bug\n\nGood. Let's look at our categories:\n\nbc. $ ag cat list \n[ko4993] Issue type\n[eo6845] ├──Bug\n[hc6100] └──Feature\n\nh3. Connect issues to categories\n\nNow we can connect issues to categories:\n\nbc. $ ag list\n[br9077]+5   Implement XML export\n[tz9540]+5   Colors are all wrong\n\n'Implement XML export' is a feature, so let's record that:\n\nbc. $ ag connect xml[TAB] feat[TAB]\n# this will turn into: ag connect br9077-implement-xml-export hc6100-feature\n\nbc. Connected issue br9077-implement-xml-export to 1 category\n\n'Colors are all wrong' is a bug, so let's record that, too:\n\nbc. $ ag connect col[TAB] bug[TAB]\n# this will turn into: ag connect tz9540-colors-are-all-wrong eo6845-bug\n\nbc. Connected issue br9077-implement-xml-export to 1 category\n\nNow the issues are connected to the categories:\n\nbc. $ ag list\n[br9077]+5   Implement XML export (Feature)\n[tz9540]+5   Colors are all wrong (Bug)\n\nWant to see which bugs are there?\n\nbc. $ ag list bug[TAB]\n# this will turn into: ag list eo6845-bug\n\nThis gives you all issues which are connected to the 'Bug' category:\n\nbc. [tz9540]+5   Colors are all wrong (Bug)\n\nAs 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.\n\nh3. Can we start working on an issue already?\n\nAlright, let's fix that strange color bug:\n\nbc. $ ag start col[TAB]\n# this will turn into: ag start tz9540-colors-are-all-wrong\n\nbc. Switched to a new branch 'tz9540-colors-are-all-wrong'\n\nNow you've got your own topic branch to deal with that bug. Make some edits, test your code, and commit:\n\nbc. git commit\n\nAnd the commit message is already there:\n\nbc.. [tz9540]+5 Colors are all wrong\n\n# Please enter the commit message for your changes. Lines starting\n# with '#' will be ignored, and an empty message aborts the commit.\n# On branch tz9540-colors-are-all-wrong\n# Changes to be committed:\n#   (use \"git reset HEAD \u003cfile\u003e...\" to unstage)\n#\n#       modified:   hello.txt\n#\n\np. 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:\n\nbc. $ ag list \n[br9077]+5 ⇢ Implement XML export (Feature)\n[tz9540]+5 ⇒ Colors are all wrong (Bug)\n\nThe 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.\n\nIf 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:\n\nbc. $ ag commit col[TAB] \u003carguments\u003e\n\nThis will perform a git commit as if you were in the specified topic branch, passing along all following arguments.\n\nh3. Resolving issues\n\nNow 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):\n\nbc. $ ag rm col[TAB]\nRemoving issue: [tz9540]+5 Colors are all wrong\nAre you sure you want to remove this issue [y/N]? \n\nType '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.\n\nh3. Wrap up\n\nNow 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:\n\nbc. $ ag new bug[TAB]\n\nThe newly created issue will be connected to @eo6845-bug@.\n\nOh, here's what you get when you type @ag help@:\n\nbc.. Ag - issue tracking intertwined with Git\n\nUsage: ag \u003ccommand\u003e [\u003cargs\u003e]\n\nAvailable category-related commands:\ncat new       Create a new category\ncat list      List all categories\ncat show      Show raw category information\ncat edit      Edit a new category\ncat reparent  Re-define the parent category of a category\ncat rm        Remove a category\n\nAvailable issue-related commands:\nnew           Create a new issue\nlist          List all issues\nshow          Show raw issue information\noneline       Show condensed issue information in a single line\nedit          Edit an issue\nconnect       Connect an issue to a category\ndisconnect    Disconnect an issue from a category\nstart         Start working on an issue\nlocate        Find commits and corresponding branches for an issue\nrm            Remove an issue\nrestore       Restore a previously removed issue\ncommit        Commit using an issue, regardless of the current branch\n\nMiscellaneous commands:\npull          Pull upstream changes\npush          Push changes upstream\nsearch        Search for categories or issues\nlog           Show of a log of Ag activities\nvisualize     Launch a web browser and visualize commits\nhelp          Show usage information\n\nSee 'ag help \u003ccommand\u003e' for more information on a specific command.\nAg supports tab completion pretty well - try to specify category or \nissue IDs via keywords, they will be auto-completed.\n\n\nh2. To do\n\n* there should be a way to restore a previously deleted issue or category\n* search results should be more clear (right now, you find removed issues but you can't tell \n  from the search results that they have been deleted)\n* web interface and reporting (oh, the possibilities!)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecht%2Fag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecht%2Fag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecht%2Fag/lists"}