Fiss

Introducing Fiss (Fiss)

2025-02-20T06:00:00Z

In a world where there are a lot of tools to manage tasks, this is one more. Fiss is a CLI-based tool that exposes issues from forges (such as Foregejo) in a task-centric interface. This tool is inspired by Taskwarrior and is designed from the ground up with the intent of using multiple forges, groups/organizations, and projects as the high-level organization.

Justification

There are a lot of tools that do the same thing, managing tasks. As well-designed or powerful as they are, the main reason for writing Fiss is that they didn't work the way we needed them too.

There Is More Than One Way To Do It

— Larry Wall

Fiss does, but isn't to say we haven't tried to find another alternative. We have, for many years and many attempts to find the “one perfect tool” for us.

Taskwarrior

Taskwarrior is very powerful, but it doesn't work well outside of the CLI. In our experience, the web services for sharing tasks across machines work fairly well, but are cumbersome to set up.

The support on Android, our current phone operating system, is relatively poor.

In many cases, the other services end up packaging Taskwarrior inside them to perform the various calculations because Taskwarrior is also very complex and not well documented. At least, it seems that way since there are not many Taskwarrior-compatible alternatives. Even the Android packages we found effectively said they packaged Taskwarrior inside them.

iCalendar

We love iCalendar (.ics) files. With our local NextCloud server, it is great for handling a lot of our common tasks.

Working with a Linux CLI and .ics is difficult. We've tried a number of different ways over the years and haven't found anything that works the way we want. Or consistently.

Introduction

Right now, this tool is barely alpha. It requires a lot of manual editing of the configuration file as documented on the website.

Adding a Server

Adding a server is pretty simple. A server has a short name, which is used by the tabular output and to reference the server.

export FISS_SERVER=mfgames
export SERVER_URL=https://src.mfgames.com
#TOKEN=the token from Forgejo
fiss server add -s $FISS_SERVER --url $SERVER_URL --token $TOKEN
fiss server add --url $SERVER_URL --token $TOKEN

It will also automatically pick up FISS_SERVER from the environment. Same for FISS_GROUP and FISS_PROJECT below.)

export FISS_SERVER=mfgames
fiss server add --url $SERVER_URL --token $TOKEN

It can be listed, not that it helps much.

$ fiss server list
 server   url                             forge    updated_seconds
 mfgames  https://src.mfgames.com/        forgejo  2025-02-15 13:15:41

All lists can be dumped as JSON:

$ fiss server list --json | jq
[
  {
    "server": "mfgames",
    "url": "https://src.mfgames.com/",
    "forge": "forgejo",
    "updated_seconds": "2025-02-14 18:04:54"
  }
]

They can also be dumped as Markdown:

$ fiss server list --markdown

server	url	forge	updated_seconds
mfgames	https://src.mfgames.com/	forgejo	2025-02-14 18:04:54

The reason servers are considered first-class is that we wrote Fiss to handle multiple forges at the same time. We have multiple Forgejo instances. Eventually, this tool will be expanded to also include iCalendar, SourceHut, GitLab, and GitHub. Potentially, one could have multiples of those also, so servers are part of the organization structure.

Groups

On a server, you have groups. Right now, users don't work yet, but groups are fine.

$ export FISS_GROUP=fiss
$ fiss group add -s $FISS_SERVER -g $FISS_GROUP

We decided to call the organizations and users “groups” because our “day job” uses “organizations” and it is really hard to spell that consistently while typing at speed. Using “groups” is relatively generic and is sufficient for our needs.

Projects

Projects are the third level of organization. Creatively, they are done the same way.

$ FISS_PROJECT=fiss
$ fiss project add -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

Caching

To avoid overloading the forges, we cache the issues. In the future, we periodically will refresh the data, pick up new issues, close others. Right now, you have to manually pull in the data.

fiss cache sync

⚠ Since there isn't a lot of elegance at this point, this will pick up all projects underneath a group and also download every single issue from those projects. That includes closed and open. So, it would not be a good idea to point this at any project that has a large number of issues.

There is also going to be controls for automatically subscribing to new projects, so you can choose to get all of them, or only require specific ones.

Issues

Once everything is synced, then the commands are pretty simple. To list issues:

fiss list -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

If the command is run inside a Git repository (any inner directory can work, it will find the Git root), it will attempt to pick up the server, group, and project from the remotes. Also, if there is a distinct name for a project, then -p $FISS_PROJECT would be sufficient.

If you want to list all projects inside a Git repository, the list command supports globbing for servers, groups, and slugs. This means fiss list -p '*' will show all projects no matter where you are in your directory structure. Also, multiple globbing can be done with colons, such fiss list -p fiss:mfgames-cil will list all fiss and mfgames-cil projects.

From this point on, we're going to assume you are in the Git directory or have FISS_SERVER, FISS_GROUP, and FISS_PROJECT set appropriately.

fiss list

Creating a new issue also relatively simple and there really isn't that much. The rest of the commands are assuming you are in a Git directory, or you exported

$ fiss add -t "Name of project"

This creates an issue. Right now, it just says nothing but it will eventually give you a useful message or at least emit the issue number.

There are commands to open and close tickets using -i or --issue with the issue number.

fiss issue close -i 3
fiss issue open -i 3

Example

So far, even at this basic state, it is fairly functional.

cd fiss
fiss list --markdown

id	title	state
mfgames/fiss/fiss/6	Cache foregejo API handle	open
mfgames/fiss/fiss/7	Refresh servers, groups, and projects periodically	open
mfgames/fiss/fiss/8	Show progress while syncing with server	open
mfgames/fiss/fiss/9	Teach ‘cache sync’ to only sync certain projects	open
mfgames/fiss/fiss/10	Show information after creating a new issue	open
mfgames/fiss/fiss/11	Allow for –body/-b to edit the body text	open
mfgames/fiss/fiss/12	Update to new version of foregejo API	open
mfgames/fiss/fiss/13	Implement subscriptions	open
mfgames/fiss/fiss/14	Do not show closed issues by default	open
mfgames/fiss/fiss/15	Do not show archived projects by default	open
mfgames/fiss/fiss/16	Get flake working as input for another flake	open

You can also see this list on our forge.

Future

So, we think this tool has potential. We'll be using it and improving it slowly as we find pain points or things where it doesn't work. At minimum, the goals are:

Add, create, and list tags on issues
Implement milestones
Implement sub-projects
Be able to edit other elements of the item (fiss edit -i 3)
Be able to open up the page from the CLI (fiss web -i 3)
Get it working properly with NixOS flakes
Be more elegant in retrieving issues
Implement the subscription control so we can decide to include 100s of projects automatically

Some Quality of Life Changes (Fiss)

2026-06-13T05:00:00Z

It's been over a year since there were any major changes to fiss, mostly because it did the minimum functionality we wanted and there are no other reported issues. However, that isn't to say it was perfect or not filled with bugs (you know, like fiss group list throwing a panic because it was never implemented).

Since we had a little time to work on something, we decided to address some quality of life issues that will hopefully make it more pleasant.

Progress Bars

When fiss is pointed to large collections of repositories, like Dylan's fiction sites, there are hundreds of repositories. When running fiss cache sync, it would take significant time to run because it walks through every server, group, and project that user is subscribed to. For us, we have hundreds and this takes a while because our server isn't that fast.

To give some feedback, instead of showing nothing for 30-90 seconds, we implemented a nested progress bar that shows the process.

$ fiss cache sync
sync_server_by_name server_name="mfgames"                                                                 3.9s
  ↳ sync_group_by_names server_name="mfgames" group_name="fedran-sources"                                 1.8s
    ↳ sync_project_by_names server_name="mfgames" group_name="fedran-sources" project_name="a-simple-cog" 0.1s

This only shows up if the command is entered into a terminal but it can be disabled with --show-progress never. In addition, always forces it to run even outside of a terminal, and auto does its best guess to determine if it is attached to a terminal or not.

The output isn't “pretty” but it is functionality for our purposes. The output is sent to “standard error” so redirect a command to get the JSON output won't be polluted by the output, even if --show-progress always is used. (Likewise, all console logging is also always sent to standard error for the same reason.)

More Intelligent Syncing

The above was written to help debug the one feature we were working on: being more graceful about how we sync our information with the forge. Previously, the only way to get a fresh list of issues was to use the fiss cache sync command which took some time.

$ time fiss cache sync --forge-sync always

real	0m46.598s
user	0m5.533s
sys	0m0.397s

If you can't guess from the spoiler, we have the same options: auto, never, and always implemented here.

$ time fiss cache sync --forge-sync never

real	0m3.127s
user	0m3.077s
sys	0m0.104s

It still walks through the servers and projects, but shaving forty seconds because it doesn't have to do API calls to the forge is a significant time savings.

When using auto, the default, the system now keeps track of the last time a server, group, or project was syned. It only syncs if the server or group hasn't been refreshed in a week or the project hasn't been refreshed in a day.

time fiss cache sync

real	0m3.126s
user	0m3.076s
sys	0m0.103s

That should make that aspect more useful.

Refresh On List

The third and final change was implementing syncing when running the list command. As said above, the only way to get new issues from the web was to run fiss cache sync. Now, fiss cache list also refreshes but it is more intelligent about it based on the scope.

For example, if only a project is requested, then it only syncs that project which takes considerably less time to implement (1-2 API calls at this point and usually under 100 ms with our current setup). However, if a group is requested, then it will only sync all the projects under that group.

fiss list --group fedran-sources
 id                                                title                                               state  assigned
 mfgames/fedran-sources/allegro/7                  Get automatic versioning working                    open
 mfgames/fedran-sources/allegro/6                  Get it sent to the copywriter                       open
 mfgames/fedran-sources/allegro/5                  Get it sent to the development editor               open
 mfgames/fedran-sources/allegro/4                  Create a cover a cover                              open
 mfgames/fedran-sources/coins-for-your-troubles/1  Chapters 12 and 13 need an editing pass             open
 mfgames/fedran-sources/flight-of-the-scions/2     Go through and update the various content warnings  open
 mfgames/fedran-sources/flight-of-the-scions/1     Make the book public                                open

And if fiss cache list --server mfgames is used, then it will sync all the groups and projects on that server before showing the list. Since this is automatic done (baring the use of --forge-sync), then fiss list will always get the most recent copy of the tasks that need to be done.

As, if the command is used without options, it picks up the project from the current Git repository which means fiss list is useful when inside that project's directory.

$ cd fiss
$ time fiss list
 id                    title                                                                       state  assigned
 mfgames/fiss/fiss/16  Get flake working as input for another flake                                open
 mfgames/fiss/fiss/15  Do not show archived projects by default                                    open
 mfgames/fiss/fiss/13  Implement subscriptions                                                     open
 mfgames/fiss/fiss/11  Allow for --body/-b to edit the body text                                   open
 mfgames/fiss/fiss/10  Show information after creating a new issue                                 open
 mfgames/fiss/fiss/8   Show progress while syncing with server                                     open
 mfgames/fiss/fiss/7   Refresh servers, groups, and projects periodically                          open
 mfgames/fiss/fiss/6   Cache foregejo API handle                                                   open
 mfgames/fiss/fiss/20  Handle fiss list fetching from empty set                                    open
 mfgames/fiss/fiss/21  Better handling when a server is removed from the config                    open
 mfgames/fiss/fiss/22  Allow output of URL or ID when creating a new issue                         open
 mfgames/fiss/fiss/23  Configuration option for how frequently to get server, groups, or projects  open
 mfgames/fiss/fiss/24  Allow sync from list to retrieve new groups and projects found              open
 mfgames/fiss/fiss/25  Change sync to be based on *_cache instead of by name                       open
 mfgames/fiss/fiss/26  Implement issue-level syncing                                               open
 mfgames/fiss/fiss/27  Figure out why Radicle will not sync                                        open

real	0m0.036s
user	0m0.030s
sys	0m0.009s

Future

We still use this project almost every day to manage our lists, but since we're the only people appearing to use it, features will show up as we need them or something annoys us. As usual, reporting issues is already appreciated but since we have to periodically disable registration on our forge, we'll be looking into better ways of submitting issues, having discussions, or getting patches. Until then, use Dylan's contact page or contact@mfgames.com.