swim/swim.1

.TH "swim" 1 "27 MAR 2021" "" "General Operation Manual"
.SH NAME
\fBswim\fP- project board software
.SH SYNOPSIS
.nf
.fam C
\fBswim\fP [\fIoptions\fP] [\fIsubcommand|filepath\fP]
.fam T
.fi
.SH DESCRIPTION
\fBswim\fP creates project management boards, in a loosely kanban style, for the terminal that uses vi-like keybindings and commands.
.TP
\fBswim\fP supports opening and writing json files for simple portability to other frontends/clients.
.SH OPTIONS
.TP
.B
\fB-h\fP
Display usage help and exit.
.SH SUBCOMMANDS
.TP
.B
init
Creates a default board with three lanes (backlog, active, and complete). The file will be based on the name of the current directory such that running \fIswim init\fP in \fI~/my-project\fP would produce \fI~/my-project/my-project.swim\fP.
.TP
.B
\fB-color\fP
Force a color mode rather than relying on \fBswim\fP's autodetection. Available options: \fIsimple\fP, \fI256\fP, \fItrue\fP, \fInone\fP. The first three can all potentially be detected and chosen by the software itself. The final option, \fInone\fP, is the only option that must be passed with the \fB-color\fP option to be a possible value. \fInone\fP removes all color codes from the program leaving just the terminal's default foreground and background colors (plus bold and inversions). This can be a good option for creating a high contrast environment.
.SH COMMANDS
.SS  LANE VIEW KEY COMMANDS
These commands work as a single keypress while on the \fBlane view screen\fP while \fBswim\fP is not taking in a line based command or prompting for action. This is the default command mode and screen of \fBswim\fP.
.TP
.B
h, l
Move focus one lane to the left (h) or right (l)
.TP
.B
j, k
Move focus one story down (j) or up (k)
.TP
.B
H, L
Move focused story one lane to the left (H) or right (L)
.TP
.B
J, K
Move focused story one story down (J) or up (K) in the current lane
.TP
.B
Q
Quit \fBswim\fP immediately
.TP
.B
N
Create a new lane, will query for lane name
.TP
.B
n
Create a new story in the focused lane, will query for story name
.TP
.B
<enter>
View the currently focused story
.TP
.B
g
Move the selection to the frist (top) story of the currently focused lane
.TP
.B
G
Move the selection to the last (bottom) story of the currently focused lane
.TP
.B
:
Enter command mode; all commands work from story or lane view
.TP
.B
+
Zoom in; show fewer, but wider, lanes on the screen
.TP
.B
-
Zoom out; show more, but narrower, lanes on the screen
.SS  STORY VIEW KEY COMMANDS
These commands work as a single keypress while on the \fBstory view screen\fP while \fBswim\fP is not taking in a line based command or prompting for action. This is the default command mode for the story view and all of the following commands operate on the story being viewed.
.TP
.B
h
Return to the \fIlane view\fP
.TP
.B
j
Scroll down
.TP
.B
k
Scroll up
.TP
.B
g
Scroll to top
.TP
.B
Scroll to bottom
.TP
.B
:
Enter command mode; all commands work from story or lane view
.TP
.B
c
Add a new comment; will query for comment value
.TP
.B
t
Add a new task; will query for task value
.TP
.B
T
Set a new story title; will query for title value
.TP
.B
d
Set a new story description; will query for description value
.TP
.B
D
Delete a task; will query for task number
.TP
.B
u
Toggle assigned user(s); will query for a space separated list of users and will toggle each suer's state on/off (if they are already assigned to the card they will be removed, otherwise they will be added)
.TP
.B
1, 2, 3, 4, 5, 6, 7, 8, 9, 0
Will toggle the task with the given number (un)complete. \fI0\fP represents \fI10\fP. This is provided as a much quicker way to toggle tasks than ahving to type a line command like \fI:toggle 2\fP of the like
.SS  LINE COMMANDS
Command mode can be accessed via the "hot" key \fI:\fP. Most of the commands can be abbreviated. For example: \fI:set story points 2\fP could also be \fI:s s p 2\fP or \fI:s st points 2\fP. In most cases any portion of the word will work. The commands can be run from any screen.

.TP
.B
write
Accepts an optional filepath, which can be relative. Will write the current board state to the given file. If no filepath is provided, the current boards path will be used. If there is no current path, as happens when swim is invoked with no path argument, the user will be queried for a save path.
.TP
.B
wq
The same as \fIwrite\fP but quits the program immediately after saving.
.TP
.B
create
Accepts a target (\fIlane\fB, \fIstory\fP, \fItask\fP, or \fcomment\fP) and an optional value. The value can be any number of words separated by spaces. For \fIlane\fP and \fIstory\fP the value will be used as the title, for the others the value will be the actual value of the target. If no value is passed the user will be queried for input.
.TP
.B
delete
Accepts a target (\fIlane\fP, \fIstory\fP, \fItask\fP). The first two always refer to the currently selected \fIlane\fP and \fIstory\fP respectively. \fItask\fP accepts an optional task number value; if no value is passed the user will be queried for input.
.TP
.B
quit
Quits the program immediately. To save and quit use \fIwq\fP.
.TP
.B
regexp
Accepts three required arguments: target (\fIbaord\fP, \fIlane\fP, \fIlanes\fP, \fIstory\fP, \fIstories\fP, and \fIstories!\fP), location (\fItitle\fP, and for story: \fIdescription\fP), and an expression representing a substitution in the form of \fI/[match expresion]/[substitution]/\fP. Matching is done with golang style regular expressions and flags can be added inline as a part of the expression. Example: \fIregexp story title /^My/Your/\fP. \fIlanes\fP and \fIstories\fP will apply the regex to all lanes or to all stories in the current lane. To target all stories on the whole board use \fIstories!\fP. Standard command abbreviation rules apply for all targets and locations with the exception of \fIlanes\fP, \fIstories\fP, and \fIstories!\fP, which must be written out fully.
.TP
.B
set
Sets a value for a particular target and location. Available targets are \fIboard\fP, \fIlane\fP, and \fIstory\fP. All three have a \fItitle\fP location. \fIstory\fP also has \fIdescription\fP, \fIpoints\fP, and \fIuser\fP. All commands accept an optional fourth argument representing the new value to set the location to. If no fourth argument, which can be many space separated words, is not passed the user will be queried for input. Many of the story locations can be modified via a key command but exist here to allow for user workflow preference. Example: \fIset lane title My Cool Lane\fP.
.TP
.B
toggle
Marks a task as (in)complete (toggles its state). Accepts an optional argument representing a task number for the currently focused story; if no value is passed the user will be queried for input.
.TP
.B
user
Accepts a space separated list of usernames to (un)assign (toggles each name's state); if no value is passed the user will be queried for input. This functions the same as \fIset story user\fP, but is less to type.
.SH BUGS
There are very likely bugs. This software was largely made for personal use and is being made available so that others can modify it to their needs if they would like. Feel free to fork and patch as you see fit (within the terms of the Floodgap Free Software License).
.SH LINKS
\fBswim\fP maintains a presence in the following locations:
.TP
.B
Source Code Repository
\fIhttps://tildegit.org/sloum/swim\fP
.SH AUTHORS
\fBswim\fP was developed by sloum
.SH LICENSE
\fBswim\fP is available under the terms of the Floodgap Free Software License: \fIhttps://www.floodgap.com/software/ffsl/license.html\fP