Today, I'm announcing the release of vgstash, a command line program that keeps track of your game collection and progress in a small SQLite database. I'm happy to finally bring this to fruition. The story of its inception follows.

Inspiration

I was having a conversation on IRC about Python, lamenting my lack of project ideas to learn the language better. During the conversation, I mentioned a game manager I wanted to make, but I was hesitant to begin working on it until I was sure I'd accounted for all semantic use cases. One person said, "What's important to you about this tool?" That was the tipping point that got the ol' gears turning. Why did I have this idea in the first place?

I wanted a good way to manage my games without relying on an outside entity. Did I care about it being a website? Not really; the mechanism didn't matter too much to me as long as it worked. Did I really care if other people used it? Was I interested in launching a website, building interest and engaging with the public about it? Not really; socialization's never been my strong point, and I wasn't ready for the consequences of gaining popularity: expectations, feature requests, and considerable time to refine it.

However, I strongly believe in the mantra of libre software: scratching your own itch. So I identified the itch ("I need a game manager") and felt Python was a great fit for it, since it comes with an SQLite3 module out of the box, a good argument parsing module, and lots of options for data serialization. At that point, the hard work was already done for me: scope.

Implementation

Determining the scope of your project is important. It allows you to form opinions on the data format it should rely on, which will help forge the path for your implementation. This distinction is important; many programmers approach it from a skeleton, a design document, or ad hoc. Some projects work really well for that. Projects that deal with data storage and manipulation (that is, most of them) should care very much about their data format. If you nail the format, the rest of the code pretty much writes itself.

vgstash's data format is as simple as I could make it without losing important features. Nailing down this narrowed scope was almost liberating. My idea of a game manager went from a grandiose Gordian knot of complexity to a command line tool that plays nicely with others. ¹ Because of this, I got a number of features for free: simple searching (thanks to grep), text manipulation (awk, cut, and friends), and data serialization (pyyaml). This cut the amount of time necessary to write the program, and it still supports everything I aimed for. This simplicity assists in code maintenance; vgstash is nowhere near complete or "correct", but it's important to do 80% of the job decently than obsess over 100% perfection. Releasing a project and gaining attention gives it momentum, and an incentive to continue development.

Usage

The documentation is still a bit rough for now. It works a lot like git in some ways. Here's a scenario (output is after a >):

# I just picked up a game, let's add it to my collection!
# It's Dark Souls for the PS3
# I own it now, but I've never played it so it's [f]resh.
$ vgstash add "Dark Souls" PS3 y f
# > Added Dark Souls for PS3. You own it and it's fresh.

# Show me a list of my games!
$ vgstash list

# Okay I got a nice table, which ones have I beaten?
$ vgstash list beaten

# Nice, nice. Well, I just beat Dark Souls. What now?
$ vgstash list -r | grep -i "Dark Souls" | cut -d '|' -f 1
# > 45

# That gave me the game's ID... Let's update it
$ vgstash update 45 progress b
# > Dark Souls on PS3 is now marked beaten.

You may notice that updating is a two-step process. You have to know the ID of the game in order to update it. That's a ripe case for automation. vgstash was designed to allow for that. In fact, I wrote a tentative shell script (found in the repository) that will help you interactively update a game. Just give it an argument to pass to grep and it takes care of the rest.

Philosophy

Command line programs often use similar interfaces, and play nicely with piping. Piping allows the user to bring out the full capability of the *nix environment by treating programs as filters for text streams. It means programs are smaller and more dedicated to a task. vgstash just stores your game collection and gives you a set of commands to work with it. Other features (searching, interactively updating, fancy interfaces, etc) should be handled by other programs, so users can build and/or use scripting to their advantage. This phenomenon is known as the UNIX philosophy:

"Do one thing, and do it well."

That said, vgstash and any helper scripts in question are considered experimental quality, so treat them accordingly.

I'm extremely happy to have built this tool and hope that others find it useful, too. Patches, comments, and suggestions are welcome.

2022-09-04 UPDATE: VGStash's CLI syntax has changed somewhat since the announcement, and is available via PyPI! Visit the VGStash PyPI Project Page for the latest release information.

I have done some rudimentary testing on Windows and it appears to work in a Command Prompt on Windows 7. I am in need of Windows-based testers, for cmd.eme, PowerShell, MinGW, and/or WSL2. OS X users shouldn't have any issues interfacing with VGStash, as long as pip's install path is somewhere in $PATH.