7.3 KiB
swim - project board software
swim is a project/task management helper that organizes projects into "swim lanes". The lanes can contain "stories" that represent a subproject. These subprojects can have titles, descriptions, assigned users, a point representation of their difficulty, a task list, and comments. Stories can be moved around within and between lanes to represent their current state in the project. A common layout for simple projects is to have three lanes: backlog, active, complete; but many other working models are possible.
Building and Installing
You will need a Go compiler. Testing on early versions has not been done, but suffice to say you should likely not need the latest cutting edge Go version to compile swim.
A Makefile has been provided with targets for make
to just build in the local directory and [sudo] make install
to install on the system along with the manpage. If you do not care about the manpage you can run go build
or go install
.
Usage
swim has a number of commands and "hot" keys. They will be detailed in this section, but are also avialable via the manpage.
The main view of the program is the swim lane
view. You can add as many lanes as you like. Lanes have titles and contain stories. A story shows up in a lane as the story title on the first row of the card and the assigned users (initials) and the number of story points together on the second row of the card.
When viewing a story you will see the story title, when the story was last updated, the user(s) assigned to the story, a description of the story, a checklist in the form of tasks, and a comments section.
"Hot" Keys
These can be pressed at appropriate times to quickly control the board/program.
Lane View
These keys have the following effect while looking at the main 'swim lane' view:
h
- Move focus one lane to the leftj
- Move focus one story downk
- Move focus one story upl
- Move focus one lane to the right- 'H' - Move focused story one lane to the left
- 'J' - Move focused story one story down in the current lane
- 'K' - Move focused story one story up in the current lane
- 'L' - Move focused story one lane to the right
Q
- Quit swim immediatelyN
- Create a new lane, will query for lane namen
- Create a new story in the focused lane, will query for story name<Enter>
- View the currently focused storyg
- Move focus to the first (top) story in the currently focused laneG
- Move focus to the last (bottom) story in the currently focused lane:
- Enter command mode; all commands work from any view/screen+
- Zoom in; show fewer, but wider, lanes on the screen at one time-
- Zoom out; show more, but narrower, lanes on the screen at one time
Story View
While looking at a story's detailed view these keys have the following effects to the story being viewed:
h
- Return to 'swim lane' viewj
- Scroll downk
- Scroll upg
- Scroll to topG
- Scroll to bottom:
- Enter command mode; all commands work from any viewc
- Add a new comment; will query for comment valuet
- Add a new task; will query for comment valueT
- Set a new title; will query for title valued
- Set a new description; will query for description valueD
- Delete a task, will query for task numberu
- Toggle assigned user(s); will query for a space separated list of users and will toggle each user's state on/off (if they are already on the card they will be removed, otherwise they will be added)1
,2
,3
,4
,5
,6
,7
,8
,9
,0
- Will toggle the task with the given number (un)complete.0
represents10
. This is quicker than having to type:toggle 2
or the like
Commands
Command mode can be accessed via the "hot" key :
. Most of the commands can be abbreviated. For example: :set story points 2
could also be :s s p 2
or :s st points 2
. In most cases any portion of the word will work.
This tree style listing shows commands and their sub-commands. Anything inside of {curly braces}
represents an optional value that can be added. These optional values can be as many words as you like and the command that you are issuing will put them together as needed. If an optional value is not passed as a part of the command then the user will be queried for the value and their response will be verified (with a yes/no/cancel prompt).
-
create
lane
{title}
story
- Will be added to the currently selected lane{title}
task
- Will be added to the currently selected story{value}
coment
{value}
-
delete
lane
- Always refers to the currently selected lanestory
- Always refers to the currently selected storytask
- Always refers to the currently selected story{task number}
-
quit
-
set
board
title
{value}
lane
- Always refers to the currently selected lanetitle
{value}
story
- Always refers to the currently selected storytitle
{value}
description
{value}
points
{value}
user
- {space separated list of usernames to (un)assign}
-
toggle
- Marks a task as (in)complete. Always refers to the currently selected story{task number}
-
user
- Always refers to the currently selected story{space separated list of usernames to (un)assign}
-
write
{path}
- Will use the current path if nothing is passed
-
wq
- Same aswrite
, but quits afterward{path}
- Will use the current path if nothing is passed
Files
swim writes data to files as json data representing program state. This allows swim files to be flexible. In theory an alternate client could be built around the same data models and interoperate pretty easily with swim, allowing end users choice of control application for underlying data.
Colors
Reliably getting a value for what color modes are supported for a given terminal is tricky business. swim does some sniffing and makes a conservative guess for what color mode your terminal will support. Three modes are supported: 4-bit (Simple), 8-Bit (256), and 24-Bit (True). The colors can be found in the file colors.go
and can be edited and recompiled if desired. They use ansi escape sequences and work in a mostly straightforward manner.
Any of the three color modes can be forced with the runtime flag -color
. For example:
swim -color simple ./my-file.swim
swim -color 256 ./my-file.swim
swim -color true ./my-file.swim
swim -color none ./my-file.swim
That last one, none
, will never be used automatically, but can be passed with the given flag to turn off color and just use your terminal's foreground/background colors (plus occasional bold and inverse coloring).
Sizing and Signals
swim will automatically resize and redraw when your terminal is resized. It also handled common signals well, allowing for suspend/resume job control to work nicely and for other signals (^c and ^d come to mind) to behave as expected.