schwabrak -- simple flat file based issue tracker
-I want relatively simple issue/ticket tracker. Something like Trac,
+I want a relatively simple issue/ticket tracker. Something like Trac,
Redmine or Fossil. But they require heavy dependencies (Python, Ruby),
database and they are centralised. You can not work with them offline
-and it is relatively complicated to replicate data to locally running
+and it is relatively complicated to replicate data to a locally running
copy of any of those trackers (well, except for Fossil I believe). And
-does web-interface necessary at all?
+is a web-interface necessary at all?
-What is a ticket/issue? Just some plain text descriptions, that have
+What is a ticket/issue? Just some plain text descriptions, with
attached enumerations (statuses, assignments, priorities, projects,
subsystems, severities, resolutions, etc) and a pile of append-only
comments, possibly with another file attachments. Can all of that
live in a directory with several plain text files? Can it be linked
with other issues just by making a symbolic links in deps/ subdirectory?
-Are not Git commits provide supplementary metainformation about when and
-by whom any of the change is made with that directory? Definitely yes!
+Do Git commits provide supplementary metainformation about when and
+by whom any of the change is made in that directory? Definitely yes!
And because of DVCS you get ability to keep the whole distributed copy
of the tracker on each developer's machine. You can send changes to it
asynchronously as a patch or bundle.
Basically schwabrak is mainly about a convention how to keep issues in
files, loosely similar to https://github.com/driusan/PoormanIssueTracker,
-where I borrowed idea of replacing spaces with dashes in issue names.
+from which I borrowed idea of replacing spaces with dashes in issue names.
-Issues are kept in issues/ directory. Each issue can be a part of
+Issues are kept in the issues/ directory. Each issue can be a part of
projects hierarchy: main-project/sub-proj/issue-name. Directory's name
-is the issue's brief name. Dashes should be interpreted as spaces and n
-> 1 dashes should be interpreted as n-1 dashes when converting directory
-name to a human readable issue title, as PoormanIssueTracker suggests.
-"about" file contains the description of the issue. "result" (initially
-empty) contains the closed issue resolution information.
+is the issue's brief name. Dashes should be interpreted as spaces and
+n > 1 dashes should be interpreted as n-1 dashes when converting the
+directory name to a human readable issue title, as PoormanIssueTracker
+suggests. The "about" file contains the description of the issue. The
+"result" (initially empty) contains the closed issue resolution
+information.
-"created" issue's file contains the datetime it was created. It is used
-to help sort issues by date. Unfortunately Git does not keep and restore
-mtimes, that probably can eliminate the need of separate files with the
-timestamps.
+The "created" issue's file contains the datetime it was created. It is
+used to help sort issues by date. Unfortunately Git does not keep and
+restore mtimes, which would probably eliminate the need of separate
+files with the timestamps.
Each issue can have attached tags. For keeping their set in consistent
-well-defined state, tags/ directory above the issues/ contains available
-tags for you projects.
+well-defined state, the tags/ directory above the issues/ contains
+available tags for your projects.
+
$ for tag in status:open status:done assigned:alice assigned:bob
- doc db test:integration severity:high severity:low ... ; do
- touch tags/$tag
+ doc db test:integration severity:high severity:low ... ; do
+ touch tags/$tag
done
+
It is your choice how to name and deal with them. Want to find all
issues in done state? for i (issues/**/tags/status:done) print $i:h:h.
-All of that kind of information are just enumerations.
+This kind of information are all just enumerations.
-deps/ subdirectory in each issue can contain symbolic link to another
-issue, referencing it. Create another kind of links between them as you
-wish.
+The deps/ subdirectory in each issue can contain symbolic links to
+another issues, referencing it. Create another kind of links between
+them as you wish.
Want to search among the issues? Just use git grep, or ordinary grep!
Want to search through attached PDFs or other kind of documents? You are
the whole history of changes related to specific issues? Just run
git log issues/issue-name! You can add a tag by simply touching
issues/issues-name/tags/tag, but "tag-add" included in schwabrak creates
-symbolic links to tags/tag and checks if the tags is known beforehand,
-to keep tags set consistent. Want to remove tag? (git) rm
+symbolic links to tags/tag and checks if the tag is known beforehand,
+to keep the tags set consistent. Want to remove a tag? (git) rm
issues/issues-name/tags/tag!
-"comment" issue's file is intended to keep the last comment related to
+The "comment" issue's file is intended to keep the last comment related to
the issue. By committing it you automatically accompany it with your
(commit's author) name and the time it was added.
+
$ cat > issues/issues-name/comment <<EOF
Here are my thoughts:
* bla bla bla
EOF
$ git commit issues/issues-name/comment
+
And you can view all comments/authors history later just with:
+
$ git log -p issues/issues-name/comment
+
Or by using "comment-list" command included in that distribution.
And of course you can add additional files with each commit.
schwabrak includes a bunch of utilities to slightly ease dealing with
all of that data. Personally I "hash -d" schwabrak's directory to be
able to quickly call commands from it:
+
$ hash -d s=~/work/schwabrak
$ cd my/issues
$ ~s/add proj/issue name to create
-To ease new issue's directory structure creation you can use "add"
-command as seen above. And yes, that is intended that "proj/issue" and
-"name", "to", "create" can be passed as separate arguments, but
-proj/issue-name-to-create will be created as expected.
-All utilities strip off possible "issues/" prefix from issues name, so
-you can easily complete issue names with something like fzf. "cd"
-utility exactly runs fzf to show you available issues, outputing path to
-selected one.
+To ease the creation of the new issue's directory structure, you can
+use "add" command as seen above. And yes, it is intended that
+"proj/issue" and "name", "to", "create" can be passed as separate
+arguments, but proj/issue-name-to-create will be created as expected.
+
+All utilities strip off possible "issues/" prefix from the issues
+name, so you can easily complete issue names with something like fzf.
+"cd" utility exactly runs fzf to show you available issues, outputing
+path to selected one.
"list" lists all issues in tab separated format, sorting by descending
creation date and showing their tags. "tag-list issue" prints issue's
human friendly way.
comment-list, recfile-export and recfile-export-all produces
-recutils'es compatible recfile output, that can is machine friendlier.
+recutils'es compatible recfile output, which is machine friendlier.