vgstash is a tool used to keep track of a video game collection. In addition to basic inventory maintenance, vgstash supports the ability to clarify whether or not the user owns a game, and their progress through said game. This makes it easy to manage a backlog and serve as a "memory" for which games someone has finished. # Concept Essentially, vgstash just gets out of your way and lets you manage things. Nothing fancy like box art or finding games in a massive dropdown box. There are easy flags to track common searches, like "All games that are owned and haven't been beaten", making vgstash convenient. Since vgstash itself is just a front-end to an SQLite database, other interfaces to this basic database format can be built to extend the basic concept. SQLite is supported across tons of languages and platforms, so it's rather trivial to build another frontend to it. If that's not enough, vgstash also supports exporting collections as YAML or pipe-delimited lines, and importing from YAML. This makes batch-editing by a human easy with YAML, and the raw format is great for pushing vgstash's output through pipes, as any good \*nix tool should. ## Data Format The key to managing things is keeping it simple, but flexible enough to give you meaningful insight to the data itself. vgstash gets straight to business with its data format: * Name (string) * System (string) * Ownership (boolean) * Completion Level (integer) * 0 (Fresh) * 1 (In Progress) * 2 (Beaten) * 3 (Completed) There isn't a hard limit on the length of the Name or System strings. SQLite itself, however, has internal limits. Those limits may differ between platforms, so there's no guarantee that vgstash databases will work across them. The `import` and `export` functions should be used to transport vgstash databases from one platform to another, as YAML is better-standardized and easily modifiable. # Usage Using vgstash is fairly easy, for a command-line program. It accepts a handful of commands, which will be explained below: * init * add * update * delete * list * import * export ## Tips For the sake of accessibility and ease of use, there are some synonyms: When specifying ownership, `0` (zero) and `n` mean the same thing. The same is true of `1` (one) and `y`. When specifying progress, the numbers and letters can both be used: `0` is also `f` or "fresh". `1` is also `i` (lowercase I) or "in-progress". `2` is also `b` (lowercase B) or "beaten". `3` is also `c` (lowercase C) or "completed". Since vgstash relies on the shell and SQLite to function, unquoted strings are likely to not be handled well. If your data ever looks funky, try correcting it with a quoted string. Bugs or issues that are reported without quoted strings will be discarded as WONTFIX, as that's basic, sane practice in every shell under the sun. ## Getting Started Initialize the database, where your information will be stored: ~~~ vgstash init ~~~ The location of the database may be set using an environment variable. To learn more, see the Environment Variables section. ## Adding Next, add a game or two: ~~~ vgstash add "Super Mario Bros" NES y i ~~~ In the above example, we're adding *Super Mario Bros* for the NES system. We own it, and haven't beaten it yet. Let's add another: ~~~ vgstash add "Borderlands 2" PC ~~~ This command has just the basics: game name, and game platform. For the sake of simplicity, the ownership and progress flags have default values: ownership defaults to "y" for "yes" and progress defaults to "i" for "in-progress". In both cases, they are the most typical state for a video game to be added to ones collection. This can be influenced; see the Environment Variables section for more info. ## Listing vgstash has plenty of methods to interface with your game collection. The simplest listing would be "list every game in the database": ~~~ # The 'all' is optional vgstash list all ~~~ This will output a human-readable list of games you have in the database, with proper flags and unique IDs, which will come in handy later. For ease of use, `list all` will sort by system, then by title. Here's an example: ~~~ ID | Title | System | Own | Progress ---+---------------------+--------+-----+---------- 3 | Metroid | NES | * | I 1 | Super Mario Bros | NES | | C 2 | The Legend of Zelda | NES | * | B 4 | Borderlands | PC | * | F ~~~ From the above output, we can gather that we don't own *Super Mario Bros* anymore. It's been completed, however, so that's good news. We own *Zelda*, and it's been beaten, but not completed. We also own *Metroid*, but it's still in-progress. Lastly, we own Borderlands for the PC, but haven't started playing it yet. The output format is designed to be easy to read, and omits information to serve as a visual guide whenever possible. From a single glance, you should be able to spot which games you own and which haven't been started yet. ### List Filtering Seeing all of your games is great when you're just getting started, but what about after you've added your massive 500 game collection? Nobody wants to sort through screenfulls of text. That's where filtering comes in. The `list` command accepts the following filters: * **completed** List games that have been completed. * **done** List games that have been beaten *or* completed. * **owned** List games that you own. * **unowned** List games that you don't own. * **wishlist** List games that you don't own AND are fresh. * **incomplete** List games that have been beaten, but not completed, that you also own. * **backlog** List games that have not been beaten or completed, that you also own. ## Update The `update` command requires the game's ID, the field you're changing, and the value you're changing it to. The fields you can change are * title * system * ownership * progress As explained in **Data Format**, ownership and progress can use single letters to substitute for the internal numeric representations. To get a game's ID, try using something like `vgstash list | grep "foo"` to find what you're looking for. ## Deleting For one reason or another, you may need to remove items from your game database. The `delete` command, coupled with the game's ID, will take care of that for you. If you want to remove *every* game from your collection, delete the `.vgstash.db` file from your $HOME directory (or whatever `VGSTASH_DB_LOCATION` is set to) and start over with `vgstash init`. # Environment Variables Customization is pretty important if you're going to manage hundreds of games. There are only a few, but they may come in handy for you! * `VGSTASH_DB_LOCATION` Defaults to `$HOME`. A file named `.vgstash.db` will be found there. * `VGSTASH_DEFAULT_OWNERSHIP` Can be 0 or 1. Default is 1 (yes). * `VGSTASH_DEFAULT_PROGRESS` Can be 0 through 3. Default is 1 (in-progress). * `VGSTASH_TABLE_WIDTH` The width of the table output by the `list` command. For readability reasons, vgstash will only allow values that are 50 or above. If this variable is set to zero (0) however, it will expand to fit the entire width of your terminal/tty. It defaults to 80 characters. # Contributing vgstash was first written in Python 3.4. There are no plans to produce a Python 2.x version. Patches and pull requests are welcome! However, please do not contribute to this project unless you are fine with your contributions also being licensed under the GPL 3.0. This is to simplify licensing issues and keep things neat. Before submitting a Pull Request, please ensure that your commit(s) contain an addition of your name to the `AUTHORS` file. Others may not use GitHub (or even git) to get or use vgstash, and every contributor deserves recognition. An example of what one would add to the `AUTHORS` file is: ~~~ John Q. Public, GitHub: @hellomynameisjohn Corrected typos in manpage ~~~ Note that the indent is four spaces. # Roadmap vgstash is considered beta-quality at this time. Please report any issues, bugs, or even suggestions on how to improve vgstash. One feature that will not be built (at least by zlg) is search functionality. Since vgstash cooperates with piping, it's trivial to pass its output through other programs and get the fine-grained information a more advanced user may need. Here are the current goals: * manpage * bash-completion file * refined argument handling for shorthand commands # Copyright vgstash is Copyright © 2016 Ze Libertine Gamer. It is licensed under the GNU General Public License, version 3.0. A copy of this license may be found in the `COPYING` file within this project. It may also be found on the World Wide Web at http://gnu.org/licenses/gpl-3.0.html.