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 https://github.com/driusan/PoormanIssueTracker,
  24 from which I borrowed idea of replacing spaces with dashes in issue names.
  25
  26 Issues are kept in the issues/ directory. Directory's name is the
  27 issue's brief name, prepended with datetime for sorting purposes. Dashes
  28 should be interpreted as spaces and n > 1 dashes should be interpreted
  29 as n-1 dashes when converting the directory name to a human readable
  30 issue title, as PoormanIssueTracker suggests. The "about" file contains
  31 the description of the issue. The "result" (initially empty) contains
  32 the closed issue resolution information.
  33
  34 Each issue can have attached tags. For keeping their set in consistent
  35 well-defined state, the tags/ directory above the issues/ contains
  36 available tags for your projects.
  37
  38     $ for tag in status:open status:done assignee:alice assignee:bob
  39         doc db test:integration severity:high severity:low ... ; do
  40             touch tags/$tag
  41     done
  42
  43 It is your choice how to name and deal with them. Want to find all
  44 issues in done state? for i (issues/**/tags/status:done) print $i:h:h.
  45 This kind of information are all just enumerations.
  46
  47 Project's name is expected to be "proj:NAME" tag for example.
  48
  49 The deps/ subdirectory in each issue can contain symbolic links to
  50 another issues, referencing it. Create another kind of links between
  51 them as you wish.
  52
  53 Want to search among the issues? Just use git grep, or ordinary grep!
  54 Want to search through attached PDFs or other kind of documents? You are
  55 free to index issues/ directory with something like recoll. Want to see
  56 the whole history of changes related to specific issues? Just run
  57 git log issues/issue-name! You can add a tag by simply touching
  58 issues/issues-name/tags/tag, but "tag-add" included in schwabrak creates
  59 symbolic links to tags/tag and checks if the tag is known beforehand,
  60 to keep the tags set consistent. Want to remove a tag? (git) rm
  61 issues/issues-name/tags/tag!
  62
  63 The "comment" issue's file is intended to keep the last comment related to
  64 the issue. By committing it you automatically accompany it with your
  65 (commit's author) name and the time it was added.
  66
  67     $ cat >issues/issues-name/comment <<EOF
  68     Here are my thoughts:
  69     * bla bla bla
  70     EOF
  71     $ git commit issues/issues-name/comment
  72
  73 And you can view all comments/authors history later just with:
  74
  75     $ git log -p issues/issues-name/comment
  76
  77 Or by using "comment-list" command included in that distribution.
  78 And of course you can add additional files with each commit.
  79
  80 schwabrak includes a bunch of utilities to slightly ease dealing with
  81 all of that data. Personally I "hash -d" schwabrak's directory to be
  82 able to quickly call commands from it:
  83
  84     $ hash -d s=~/work/schwabrak
  85     $ cd my/issues
  86     $ ~s/add issue name to create
  87
  88 To ease the creation of the new issue's directory structure, you can use
  89 "add" command as seen above. And yes, it is intended that "issue" and
  90 "name", "to", "create" can be passed as separate arguments, but
  91 proj/issue-name-to-create will be created as expected.
  92
  93 All utilities strip off possible "issues/" prefix from the issues
  94 name, so you can easily complete issue names with something like fzf.
  95 "cd" utility exactly runs fzf to show you available issues, outputting
  96 path to selected one.
  97
  98 "list" lists all issues in tab separated format, sorting by descending
  99 creation date and showing their tags. Optional arguments acts like a
 100 filter for the issue's tags.
 101
 102     $ ~s/list open stargrave !hidden
 103
 104 That will list all issues with the tags including "status:open" AND
 105 "assignee:stargrave", AND excluding issues with the tags containing
 106 "hidden". Each argument is an expression each issue's tag is compared to
 107 (zsh'es "=~" test). Tag with "!"-prefix means that no tag should be in
 108 issue's set.
 109
 110 "tag-list issue" prints issue's tags if any.
 111 "tag-add issue [tags/]tag" adds a tag, as was noticed before.
 112 "dep-add issue-dst issue-src" will link issue-src in issues-dst's deps/.
 113 "show issue" shows most of issue's information in human friendly way.
 114 "comment" allows you to conveniently add comment.
 115
 116 comment-list, recfile-export and recfile-export-all produces
 117 recutils'es compatible recfile output, which is machine friendlier.