--- /dev/null
+schwabrak -- simple flat file based issue tracker
+
+I want 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
+copy of any of those trackers (well, except for Fossil I believe). And
+does web-interface necessary at all?
+
+What is a ticket/issue? Just some plain text descriptions, that have
+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!
+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.
+
+Issues are kept in 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.
+
+"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.
+
+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.
+ $ for tag in status:open status:done assigned:alice assigned:bob
+ 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.
+
+deps/ subdirectory in each issue can contain symbolic link to another
+issue, 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
+free to index issues/ directory with something like recoll. Want to see
+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
+issues/issues-name/tags/tag!
+
+"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.
+
+"list" lists all issues in tab separated format, sorting by descending
+creation date and showing their tags. "tag-list issue" prints issue's
+tags if any. "tag-add (issues/)issue (tags/)tag" adds a tag, as was
+noticed before. "dep-add issue-dst issue-src" will link issue-src in
+issues-dst's deps/. "show issue" shows most of issue's information in
+human friendly way.
+
+comment-list, recfile-export and recfile-export-all produces
+recutils'es compatible recfile output, that can is machine friendlier.