diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 115 | ||||
| -rw-r--r-- | README.mdown | 279 |
2 files changed, 115 insertions, 279 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d42320 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +# vgstash - a place to stash your game collection + +If you love video games, you've probably amassed a collection of them, across +many different systems; physical, digital, and everything in-between. At some +point, a player may want to know a few key pieces of information that may steer +their gaming. These questions are great for quelling boredom and keeping a +gaming backlog manageable: + +* Which games do I own? +* Which games have I beaten or completed? +* Which games do I need to beat? +* What was the note I left for X game? + +vgstash seeks to answer these type of questions in a simple and extensible way. + +# Installation + +vgstash is available via `pip`: + +~~~ +pip install [--user] vgstash +~~~ + +Packages for vgstash on Gentoo Linux and Adélie Linux are on the TODO list. + +Please note that vgstash is under heavy development at present. Do not install +unless you are interested in helping its development. + +# Concept + +The core concept of vgstash is the game itself. Every game in a player's +collection has a few important attributes, all of which are obvious to the +player: + +* Title +* System +* Ownership + * unowned + * physical + * digital + * both +* Progress + * new + * playing + * beaten + * complete +* Notes + +Think of any game that you have a history with. Let's say it was a game you +bought as part of a Humble Bundle, but haven't started playing yet. Internally, +vgstash tracks it somewhat like this: + +``` +.--------------------------------------------------------. +| Title | System | Ownership | Progress | +|------------------------+--------+-----------+----------| +| FTL: Faster Than Light | Steam | digital | new | +'--------------------------------------------------------' +``` + +This is the bare minimum information you need to meaningfully track a video +game in your collection. + +vgstash comes with a command line client of the same name, which gives you +high level commands to manipulate the database with. It's the reference +implementation for a vgstash client. + +If you wanted to add the above game to your collection, you'd do it like this: + +```bash +$ vgstash add 'FTL: Faster Than Light' Steam d n +Added FTL: Faster Than Light for Steam. You digitally own it and you have not started it. +``` + +Pretty easy, huh? Each game and system added to vgstash is free-form and can +be tuned to match the user's preferences. vgstash has a fairly small set of +commands: + +* add +* delete +* update +* list + +The power is in the `list` command. vgstash comes with a set of default filters +that allow you to reason about your game collection. For example, this command +will show you every game marked "playing" that you also own in some way: + +```bash +$ vgstash list playlog +# listed output here +``` + +Consult `vgstash -h` for further usage information. + +# Roadmap + +These are planned for the full 0.3 release: + +* command line interface finished +* Match feature-set with `master` + +Goals planned for the 0.4 release: + +* import and export with JSON + +Goals planned for the 0.5 release: + +* some sort of GUI (Tk and Qt are current candidates) + +Goals planned for the 1.0 release: + +* Kivy-based interface (to release on Android via F-Droid) + +If this interests you, please [e-mail me](mailto:zlg+vgstash@zlg.space) or find +me on the Fediverse: [@zlg@social.zlg.space](https://social.zlg.space/users/zlg) diff --git a/README.mdown b/README.mdown deleted file mode 100644 index ace50e6..0000000 --- a/README.mdown +++ /dev/null @@ -1,279 +0,0 @@ -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 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: - -* **arcade** - Games you own that cannot be beaten. - -* **backlog** - Games you own that have not been beaten or completed. - -* **borrowing** - Games you don't own and are playing. - -* **complete** - Games that have been completed. - -* **digital** - Games you own digitally. - -* **done** - Games that have been beaten *or* completed. - -* **incomplete** - Games you own that have been beaten, but not completed. - -* **new** - Games you own and haven't played yet. - -* **owned** - Games you own. - -* **physical** - Games you own physically. - -* **playlog** - Games you own that are marked 'playing'. - -* **unowned** - Games you don't own. - -* **wishlist** - Games you don't own *and* haven't played yet. - -## 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 -`$HOME/.vgstash.db` (or wherever `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/.vgstash.db`. - -* `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 might not be using 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 <jqp@genericville.com> - 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-2018 zlg. 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. |