README

   1 schwabrak -- simple flat file based issue tracker
   2
   3 I want 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 locally running
   7 copy of any of those trackers (well, except for Fossil I believe). And
   8 does web-interface necessary at all?
   9
  10 What is a ticket/issue? Just some plain text descriptions, that have
  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 Are not Git commits provide supplementary metainformation about when and
  17 by whom any of the change is made with 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 where I borrowed idea of replacing spaces with dashes in issue names.
  25
  26 Issues are kept in issues/ directory. Each issue can be a part of
  27 projects hierarchy: main-project/sub-proj/issue-name. Directory's name
  28 is the issue's brief name. Dashes should be interpreted as spaces and n
  29 > 1 dashes should be interpreted as n-1 dashes when converting directory
  30 name to a human readable issue title, as PoormanIssueTracker suggests.
  31 "about" file contains the description of the issue. "result" (initially
  32 empty) contains the closed issue resolution information.
  33
  34 "created" issue's file contains the datetime it was created. It is used
  35 to help sort issues by date. Unfortunately Git does not keep and restore
  36 mtimes, that probably can eliminate the need of separate files with the
  37 timestamps.
  38
  39 Each issue can have attached tags. For keeping their set in consistent
  40 well-defined state, tags/ directory above the issues/ contains available
  41 tags for you projects.
  42     $ for tag in status:open status:done assigned:alice assigned:bob
  43             doc db test:integration severity:high severity:low ... ; do
  44         touch tags/$tag
  45     done
  46 It is your choice how to name and deal with them. Want to find all
  47 issues in done state? for i (issues/**/tags/status:done) print $i:h:h.
  48 All of that kind of information are just enumerations.
  49
  50 deps/ subdirectory in each issue can contain symbolic link to another
  51 issue, referencing it. Create another kind of links between them as you
  52 wish.
  53
  54 Want to search among the issues? Just use git grep, or ordinary grep!
  55 Want to search through attached PDFs or other kind of documents? You are
  56 free to index issues/ directory with something like recoll. Want to see
  57 the whole history of changes related to specific issues? Just run
  58 git log issues/issue-name! You can add a tag by simply touching
  59 issues/issues-name/tags/tag, but "tag-add" included in schwabrak creates
  60 symbolic links to tags/tag and checks if the tags is known beforehand,
  61 to keep tags set consistent. Want to remove tag? (git) rm
  62 issues/issues-name/tags/tag!
  63
  64 "comment" issue's file is intended to keep the last comment related to
  65 the issue. By committing it you automatically accompany it with your
  66 (commit's author) name and the time it was added.
  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 And you can view all comments/authors history later just with:
  73     $ git log -p issues/issues-name/comment
  74 Or by using "comment-list" command included in that distribution.
  75 And of course you can add additional files with each commit.
  76
  77 schwabrak includes a bunch of utilities to slightly ease dealing with
  78 all of that data. Personally I "hash -d" schwabrak's directory to be
  79 able to quickly call commands from it:
  80     $ hash -d s=~/work/schwabrak
  81     $ cd my/issues
  82     $ ~s/add proj/issue name to create
  83 To ease new issue's directory structure creation you can use "add"
  84 command as seen above. And yes, that is intended that "proj/issue" and
  85 "name", "to", "create" can be passed as separate arguments, but
  86 proj/issue-name-to-create will be created as expected.
  87
  88 All utilities strip off possible "issues/" prefix from issues name, so
  89 you can easily complete issue names with something like fzf. "cd"
  90 utility exactly runs fzf to show you available issues, outputing path to
  91 selected one.
  92
  93 "list" lists all issues in tab separated format, sorting by descending
  94 creation date and showing their tags. "tag-list issue" prints issue's
  95 tags if any. "tag-add (issues/)issue (tags/)tag" adds a tag, as was
  96 noticed before. "dep-add issue-dst issue-src" will link issue-src in
  97 issues-dst's deps/. "show issue" shows most of issue's information in
  98 human friendly way.
  99
 100 comment-list, recfile-export and recfile-export-all produces
 101 recutils'es compatible recfile output, that can is machine friendlier.