Project management swim lanes for your terminal https://sloum.colorfield.space/docs/swim
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
sloum b8ce1fcd87 Makes binary resulting from makefile smaller 3 months ago
qline Fixes editable line input to work reliably on xterm derivatives, but ungeneralizes qline 6 months ago
termios Some screen drawing is happening now but it is janky 6 months ago
.gitignore Reworks commands and adds deletion of various objects 6 months ago
LICENSE Adds license, fixes bugs, adds features 6 months ago
Makefile Makes binary resulting from makefile smaller 3 months ago
README.md Adds docs for init 6 months ago
board.go Adds moving story cards around as a change requiring save verification 5 months ago
colors.go Adds mode for removing colors 6 months ago
comment.go More or less working board 6 months ago
go.mod Adds go.mod 6 months ago
lane.go Adds check to quit if there are unsaved changes 5 months ago
main.go Adds check to quit if there are unsaved changes 5 months ago
notes.md Reworks commands and adds deletion of various objects 6 months ago
story.go Adds check to quit if there are unsaved changes 5 months ago
swim-lane-view.png Adds readme update, images, and removes dead code branch 6 months ago
swim-story-view.png Adds readme update, images, and removes dead code branch 6 months ago
swim.1 Adds docs for init 6 months ago
swim.swim Integrates qline to allow for editable input lines 6 months ago
task.go More or less working board 6 months ago

README.md

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.

a screenshot of the swim lane view of the application 'swim'

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.

a screenshot of the story view of the application 'swim'

Command Line Options

swim has two command line flags: -color and -h. -color is detailed in its own section below. -h prints help text.

There is also one command line option or subcommand: init. Running swim init will create a swim file in the current working directory with three lanes (backlog, active, complete). The file will be named after the directory it is found in. So, if the working directory is ~/projects/myproject, the file created will be ~/projects/myproject/myproject.swim. This provides a quick way to get a board going without having to go through boilerplate steps. It is completely optional (it is not hard to build out a customized board).

"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 left
  • j - Move focus one story down
  • k - Move focus one story up
  • l - 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 immediately
  • N - Create a new lane, will query for lane name
  • n - Create a new story in the focused lane, will query for story name
  • <Enter> - View the currently focused story
  • g - Move focus to the first (top) story in the currently focused lane
  • G - 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' view
  • j - Scroll down
  • k - Scroll up
  • g - Scroll to top
  • G - Scroll to bottom
  • : - Enter command mode; all commands work from any view
  • c - Add a new comment; will query for comment value
  • t - Add a new task; will query for task value
  • T - Set a new title; will query for title value
  • d - Set a new description; will query for description value
  • D - Delete a task; will query for task number
  • u - 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 represents 10. 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 lane
    • story - Always refers to the currently selected story
    • task - Always refers to the currently selected story
      • {task number}
  • quit

  • regex - Uses golang style regular expressions

    • board
      • title
        • Expression in the form: /[match expression]/[replacement]/
    • lane
      • title
        • Expression in the form: /[match expression]/[replacement]/
    • lanes - Applies the expression to all lanes, abbreviating lanes is not allowed
      • title
        • Expression in the form: /[match expression]/[replacement]/
    • story
      • title
        • Expression in the form: /[match expression]/[replacement]/
      • description
        • Expression in the form: /[match expression]/[replacement]/
    • stories - Applies the expression to all stories in the current lane, abbreviating stories is not allowed
      • title
        • Expression in the form: /[match expression]/[replacement]/
      • description
        • Expression in the form: /[match expression]/[replacement]/
    • stories! - Applies the expression to all stories on the board (use with care), abbreviating stories! is not allowed
      • title
        • Expression in the form: /[match expression]/[replacement]/
      • description
        • Expression in the form: /[match expression]/[replacement]/
  • set

    • board
      • title
        • {value}
    • lane - Always refers to the currently selected lane
      • title
        • {value}
    • story - Always refers to the currently selected story
      • title
        • {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 as write, 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.

Examples

A file, swim.json, is included with this repository. It has been used to track work on the project itself (at least since file i/o was added) and can serve as a simple example and a way to try navigating around the program with some data already present.

License

A license file is included in the repo. If for some reason you have this readme but not the license file, it can be viewed on the web via floodgap.