README

   1 schwabrak -- simple flat file based issue tracker
   2
   3 I want a relatively simple issue/ticket tracker. Something like Trac,
   4 Redmine or Fossil. But they require heavy dependencies (Python, Ruby),
   5 database and they are centralised. You can not work with them offline
   6 and it is relatively complicated to replicate data to a locally running
   7 copy of any of those trackers (well, except for Fossil I believe). And
   8 is a web-interface necessary at all?
   9
  10 What is a ticket/issue? Just some plain text descriptions, with
  11 attached enumerations (statuses, assignments, priorities, projects,
  12 subsystems, severities, resolutions, etc) and a pile of append-only
  13 comments, possibly with another file attachments. Can all of that
  14 live in a directory with several plain text files? Can it be linked
  15 with other issues just by making a symbolic links in deps/ subdirectory?
  16 Do Git commits provide supplementary metainformation about when and
  17 by whom any of the change is made in that directory? Definitely yes!
  18 And because of DVCS you get ability to keep the whole distributed copy
  19 of the tracker on each developer's machine. You can send changes to it
  20 asynchronously as a patch or bundle.
  21
  22 Basically schwabrak is mainly about a convention how to keep issues in
  23 files, loosely similar to
  24 https://github.com/driusan/PoormanIssueTracker,
  25 https://github.com/driusan/IssueTrackerTools,
  26 https://github.com/aaiyer/bugseverywhere,
  27 https://www.youtube.com/watch?v=ysgMlGHtDMo
  28 from which I borrowed idea of replacing spaces with dashes in issue
  29 names.
  30
  31 Issues are kept in the issues/ directory. Directory's name is the
  32 issue's brief name, prepended with datetime for sorting purposes. Dashes
  33 should be interpreted as spaces and n > 1 dashes should be interpreted
  34 as n-1 dashes when converting the directory name to a human readable
  35 issue title, as PoormanIssueTracker suggests. The "about" file contains
  36 the description of the issue. The "result" (initially empty) contains
  37 the closed issue resolution information.
  38
  39 Each issue can have attached tags. For keeping their set in consistent
  40 well-defined state, the tags/ directory above the issues/ contains
  41 available tags for your projects.
  42
  43     $ for tag in status:open status:done assignee:alice assignee:bob
  44         doc db test:integration severity:high severity:low ... ; do
  45             touch tags/$tag
  46     done
  47
  48 It is your choice how to name and deal with them. Want to find all
  49 issues in done state? for i (issues/**/tags/status:done) print $i:h:h.
  50 This kind of information are all just enumerations.
  51
  52 Project's name is expected to be "proj:NAME" tag for example.
  53
  54 The deps/ subdirectory in each issue can contain symbolic links to
  55 another issues, referencing it. Create another kind of links between
  56 them as you wish.
  57
  58 Want to search among the issues? Just use git grep, or ordinary grep!
  59 Want to search through attached PDFs or other kind of documents? You are
  60 free to index issues/ directory with something like recoll. Want to see
  61 the whole history of changes related to specific issues? Just run
  62 git log issues/issue-name! You can add a tag by simply touching
  63 issues/issues-name/tags/tag, but "tag-add" included in schwabrak creates
  64 symbolic links to tags/tag and checks if the tag is known beforehand,
  65 to keep the tags set consistent. Want to remove a tag? (git) rm
  66 issues/issues-name/tags/tag!
  67
  68 The "comment" issue's file is intended to keep the last comment related to
  69 the issue. By committing it you automatically accompany it with your
  70 (commit's author) name and the time it was added.
  71
  72     $ cat >issues/issues-name/comment <<EOF
  73     Here are my thoughts:
  74     * bla bla bla
  75     EOF
  76     $ git commit issues/issues-name/comment
  77
  78 And you can view all comments/authors history later just with:
  79
  80     $ git log -p issues/issues-name/comment
  81
  82 Or by using "comment-list" command included in that distribution.
  83 And of course you can add additional files with each commit.
  84
  85 schwabrak includes a bunch of utilities to slightly ease dealing with
  86 all of that data. Personally I "hash -d" schwabrak's directory to be
  87 able to quickly call commands from it:
  88
  89     $ hash -d s=~/work/schwabrak
  90     $ cd my/issues
  91     $ ~s/add issue name to create
  92
  93 To ease the creation of the new issue's directory structure, you can use
  94 "add" command as seen above. And yes, it is intended that "issue" and
  95 "name", "to", "create" can be passed as separate arguments, but
  96 proj/issue-name-to-create will be created as expected.
  97
  98 All utilities strip off possible "issues/" prefix from the issues
  99 name, so you can easily complete issue names with something like fzf.
 100 "cd" utility exactly runs fzf to show you available issues, outputting
 101 path to selected one.
 102
 103 "list" lists all issues in tab separated format, sorting by descending
 104 creation date and showing their tags. Optional arguments acts like a
 105 filter for the issue's tags.
 106
 107     $ ~s/list open stargrave !hidden
 108
 109 That will list all issues with the tags including "status:open" AND
 110 "assignee:stargrave", AND excluding issues with the tags containing
 111 "hidden". Each argument is an expression each issue's tag is compared to
 112 (zsh'es "=~" test). Tag with "!"-prefix means that no tag should be in
 113 issue's set.
 114
 115 "tag-list issue" prints issue's tags if any.
 116 "tag-add issue [tags/]tag" adds a tag, as was noticed before.
 117 "dep-add issue-dst issue-src" will link issue-src in issues-dst's deps/.
 118 "show issue" shows most of issue's information in human friendly way.
 119 "comment" allows you to conveniently add comment.
 120
 121 comment-list, recfile-export and recfile-export-all produces
 122 recutils'es compatible recfile output, which is machine friendlier.