cil - the command-line issue list
$ cil init
$ cil summary
$ cil list
$ cil list --status=New
$ cil list --label=Release-v0.1
$ cil list --is-open
$ cil add
... added issue 'cafebabe' ...
$ cil show cafebabe
$ cil edit cafebabe
$ cil status cafebabe InProgress
$ cil comment cafebabe
... added comment 'deadbeef' ...
$ cil attach cafebabe filename.txt
... added attachment 'decaf7ea' ...
$ cil extract decaf7ea
$ cil extract decaf7ea --filename=other_filename.txt
$ cil am email.txt
$ cil track
$ cil fsck
Cil is a small but useful command-line issue list. It saves issues, comments and attachments as local files which you can check in to your repository.
Creates a local '.cil' file and an 'issues' directory. If PATH is specified, the config file and directory will be created in the destination directory.
Usually, cil will write a small .cil file such that you can use various
filter commands immediately and can also serve as an example config file. Using
--bare just touches the .cil config file ready for your own manipulation.
Displays a one line summary for each issue. You may filter on both the Status and Label fields.
Shows each issue with more information. You may filter on both the Status and Label fields.
Adds an issues after you have edited the input. Text passed after 'add' will be used as the bug summary line.
Shows the issue name with more detail.
Shortcut so that you can set a new status on an issue without having to edit it.
Shortcut so that cil will add a 'DependsOn' from issue 1 to issue 2. Conversley, issue 2 will also then contain a 'Precedes' pointer to issue 1.
This is the exact opposite of depends-on and is here for convenience and
completeness. ie. issue 1 has to be completed before issue 2.
Shortcut so that you can set a new status on an issue without having to edit it.
Shortcut to assign this issue to yourself. It reads your ~/.cilrc file for
your UserName and UserEmail and uses this to populate the AssignedTo field
in the issue.
Edits the issue. If it changes, set the updates time to now.
Adds a comment to an issues after you have edited the input.
Adds that particular filename to an existing issue.
Extracts the file from the attachment number. If filename if given uses that, otherwise it will use the original one saved along with the attachment.
Applies an email message to the issue list. It tries to figure out the type of email it is, whether it is a new issue or a comment on an already existing issue. For example, if it can find valid issue names in the subject or body of the message, it adds it as a comment to that issue. If it can't find any valid issue names, it presumes it's a new issue and adds that.
Note: this command will deal with Mailbox format files later on.
This command outputs one or more command which you should run so that your VCS knows about your issue. It makes sure all the comments and attachments are done too.
Tries to help you organise your issues if any aren't valid or have broken relationships.
Filters can be used on both the summary and list commands. Most can be
combined. See each individual filter for details.
You can choose any of the Statuses which might appear in your issues. This
status does not have to be defined in your .cil file, even if you have
StatusStrict turned on.
You can choose any of the Labels which might appear in your issues. This
label does not have to be defined in your .cil file, even if you have
LabelStrict turned on.
These check both StatusOpenList and StatusClosedList from your .cil
file. If both are specified, you're likely to get no issues unless you
explicitely defined a status as being in both lists (for whatever reason you
have).
These items are mutually exclusive. The --assigned-to just checks the email
address in the AssignedTo field. It does not match anything else in that field,
including any preceding name or any angle brackets.
The --is-mine filter is a shortcut to asking if AssignedTo is you. Cil knows
your email address if you define it in your user's ~/.cilrc file as
UserEmail.
The .cil file is used to configure bits and pieces within cil for this
particular issue list. The following options are available and where stated,
may be declared multiple times:
The .cil file is fairly simple and an example can be seen here:
VCS: Git
StatusStrict: 1
StatusAllowedList: New
StatusAllowedList: InProgress
StatusAllowedList: Finished
StatusOpenList: New
StatusOpenList: InProgress
StatusClosedList: Finished
LabelStrict: 1
LabelAllowedList: Type-Enhancement
LabelAllowedList: Type-Defect
LabelAllowedList: Priority-High
LabelAllowedList: Priority-Medium
LabelAllowedList: Priority-Low
Default: empty, Type: Enum(Git)
Currently this option only supports Git. This enables you to use the 'track' command.
Default: 0, Type: Boolean (0/1)
If this is set to a true value then cil checks that the status you enter into an issue (after adding or editing) is also in the allowed list (see StatusAllowedList).
Default: empty, Type: List
This list is checked against when adding or editing issues but only if you have StatusStrict on.
Default: empty, Type: List
This list is checked against when filtering with --is-open.
Default: empty, Type: List
This list is checked against when filtering with --is-closed.
Default: 0, Type: Boolean (0/1)
This determines that labels you enter are checked against LabelAllowedList. Set to 1 if you require this feature.
Default: empty, Type: List
This determines which labels are allowed if you have turned on LabelStrict.
The ~/.cilrc file is read to configure the user's preferences for all cil
lists they're using. It is of the same format as the .cil file and contains
the following options:
UserName: Andrew Chilton
UserEmail: andychilton@gmail.com
Default: 'Name', Type: String
This is used as a default in the CreatedBy and AssignedTo fields in any
issues/comments/attachments you add.
Default: 'Email', Type: String
This is used as a default in the CreatedBy and AssignedTo fields in any
issues/comments/attachments you add.
Probably. Let me know :-)
To get a ToDo list for cil, clone the repo, find the issues/ dir and type:
$ cil --is-open
This gives the current outstanding issues in cil.
Andrew Chilton <andychilton@gmail.com>
Copyright (C) 2008 by Andrew Chilton
Cil is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/> or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#!/usr/bin/perl ## ---------------------------------------------------------------------------- # cil is a Command line Issue List # Copyright (C) 2008 Andrew Chilton # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>. ## ---------------------------------------------------------------------------- use strict; use warnings; use Getopt::Mixed "nextOption"; use File::Touch; use File::Glob ':glob'; use File::Basename; use File::Slurp qw(read_file write_file); use Email::Simple; use Email::Date qw(find_date); use CIL; use CIL::Issue; use CIL::Comment; use CIL::Attachment; ## ---------------------------------------------------------------------------- # constants my @IN_OPTS = ( # strings 'p=s', # p = path 'path>p', # for 'add' 'f=s', # f = filename 'filename>f', # for 'extract' 's=s', # s = status 'status>s', # for 'summary', 'list' 'l=s', # l = label 'label>l', # for 'summary, 'list' 'c=s', # c = created-by 'created-by>c', # for 'summary', 'list' 'a=s', # a = assigned_to 'assigned-to>a',# for 'summary', 'list' 'r=s', # r = revision 'revision>s', # for all query commands # booleans 'bare', # for 'init' 'is-open', # for 'summary', 'list' 'is-closed', # for 'summary', 'list' 'is-mine', # for 'summary', 'list' 'help', 'version', ); my %BOOLEAN_ARGS = ( 'help' => 1, 'version' => 1, 'bare' => 1, 'is-open' => 1, 'is-closed' => 1, 'is-mine' => 1, ); ## ---------------------------------------------------------------------------- # main program { my $args = get_options(\@IN_OPTS, \%BOOLEAN_ARGS); # do the version and help if ( exists $args->{version} ) { print "cil version " . $CIL::VERSION . "\n"; exit; } if ( exists $args->{help} ) { usage(); exit; } # make sure that the command given is valid Getopt::Mixed::abortMsg('specify a command') if @ARGV == 0; my $command_name = shift @ARGV; $command_name =~ s{-}{_}gxms; my( $command ) = grep { $command_name eq $_->name } CIL->commands or Getopt::Mixed::abortMsg("'$command_name' is not a valid cil command."); my $cil = CIL->new(); $cil->read_config_user(); $cil->read_config_file(); $cil->check_args($args); # add any hooks we want # none yet $command->run($cil, $args, @ARGV); } ## ---------------------------------------------------------------------------- # hooks # none yet ## ---------------------------------------------------------------------------- # helper functions for this command line tool sub get_options { my ($in_opts, $booleans) = @_; my $args = {}; Getopt::Mixed::init( @$in_opts ); while( my($opt, $val) = nextOption() ) { # if boolean, keep a count of how many there is only if ( exists $booleans->{$opt} ) { $args->{$opt}++; next; } # normal 'string' value if ( defined $args->{$opt} ) { unless ( ref $args->{$opt} eq 'ARRAY' ) { $args->{$opt} = [ $args->{$opt} ]; } push @{$args->{$opt}}, $val; } else { $args->{$opt} = $val; } } Getopt::Mixed::cleanup(); return $args; } ## ---------------------------------------------------------------------------- # program info sub usage { print <<"END_USAGE"; Usage: $0 COMMAND [options] Commands: init [--path=PATH] add summary [FILTERS...] list [FILTERS...] show ISSUE status ISSUE NEW_STATUS steal ISSUE edit ISSUE comment ISSUE attach ISSUE FILENAME extract ATTACHMENT [--filename=FILENAME] am EMAIL.TXT track ISSUE fsck Filters: --status=? --is-open --is-closed --label=? --assigned-to=? --is-mine See <http://kapiti.geek.nz/software/cil.html> for further information. Report bugs to <andychilton\@gmail.com>. END_USAGE } ## ----------------------------------------------------------------------------
## ----------------------------------------------------------------------------