gitto-cli 0.1.0

A Git-like CLI tool for PokéPaste team version control

Gitto

What is Gitto?

Gitto is a Git-like CLI tool for tracking and managing competitive Pokémon teams using PokéPaste links.

Why use Gitto?

Because teambuilding gets messy, fast.

Gitto helps you organise, version and compare your Pokémon teams, without losing track of changes.

Gitto gives you:

• Structure: organise teams and their variants efficiently
• History: track every change you make
• Clarity: write yourself meaningful messages for every team version
• Confidence: never lose a good team again

Who is Gitto for?

Gitto is for competitive Pokémon players who frequently iterate and refine their teams, and want an efficient way to track changes and manage different versions.

Especially if your Pokémon Showdown teambuilder looks something like:

What can I do with Gitto?

• Track the full history of your team as it evolves
• Manage multiple variants of a team without messy copies
• Compare versions to see exactly what changed
• Revisit or restore any previous version
• Merge successful versions into the final team

How do I install Gitto?

From GitHub (pip)

pip install git+https://github.com/SaiNikhilTadepalli/Gitto.git

Using uv (recommended)

uv tool install git+https://github.com/SaiNikhilTadepalli/Gitto.git

From PyPI

pip install gitto

How do I use Gitto?

After installing, open Gitto from your terminal:

gitto

This starts the interactive CLI (REPL), where you can run all commands.

Gitto uses three simple ideas:

• A team is your overall project
• A variant is a different version of that team
• An update saves a snapshot from a PokéPaste URL

Gitto always shows your current context in the prompt.

When you first open it:

gitto>

Once you switch to a team and variant:

gitto(gen9uu-sun-offense/physical-venusaur)>

This helps you always know:

• which team you're working on
• which variant you're editing

Example workflow

⚠️ The PokéPaste links below are for demonstration purposes only.

Imagine you're building a Gen 9 UU sun team:

team create gen9uu-sun-offense
team switch gen9uu-sun-offense

You start with an initial draft:

team update https://pokepast.es/example-sun-draft -m "initial sun draft"

Now, you want to explore two different builds for a Chlorophyll Venusaur:

Variant 1: Special attacker

team variant special-venusaur
team use special-venusaur

team update https://pokepast.es/example-sun-special-venusaur -m "special attacker Venusaur with Growth"

Variant 2: Physical attacker (a gimmick perhaps)

team variant physical-venusaur
team use physical-venusaur

team update https://pokepast.es/example-sun-physical-venusaur -m "physical attacker Venusaur with Swords Dance experiment"

Compare ideas

To compare different variants, you first look at your timeline:

team timeline

This shows a chronological list of updates across all variants for your team, including their hashes.

Example (simplified):

[a1b2c3d] gen9uu-sun-offense/physical-venusaur: <msg>
[d4e5f6g] gen9uu-sun-offense/special-venusaur: <msg>
[h7i8j9k] gen9uu-sun-offense/main: <msg>

You can then compare any two versions using their hashes from the timeline:

team compare a1b2c3d h7i8j9k

This lets you inspect exactly how the two variants differ.

From experimentation to final team

After comparing ideas, you decide to revisit the physical Venusaur variant.

It actually performs better than expected on ladder, so you refine it and commit a final update:

team use physical-venusaur
team update https://pokepast.es/example-sun-physical-final -m "final physical Venusaur version after ladder testing"

You decide this is the version you want to keep.

Merging into your main team

You switch back to your main variant:

team use main

Then combine the successful idea from your physical variant into the main team:

team combine physical-venusaur main

Now, your main team reflects the final tested version.

Cleaning up

Since the physical variant is no longer needed, you can choose to remove it:

team discard physical-venusaur

Final state

Your team now looks like:

• main: final, ladder-tested team
• special-venusaur: archived experiment (optional to keep or discard)

Everything is:

• versioned
• reproducible
• and fully traceable

Command reference

You can also view all of the following commands any time inside Gitto:

help

Team management

team create <name>       # Create a new Pokémon team
team switch <name>       # Switch to an existing team
team list                # List all teams
team rename <old> <new>  # Rename a team
team delete <name>       # Delete a team

Variant management

team variant <name>  # Create a new experimental variant of your team
team use <name>      # Switch to an existing variant
team discard <name>  # Delete a variant
team variants        # List all variants in the current team    

Updates

team update <url> -m "message"  # Add a new update from a PokéPaste URL
team amend <url> -m "message"   # Overwrite the most recent update with new data

History & status

team status                            # Show current team, variant and latest update
team history                           # Show the history of updates in the current variant
team timeline                          # Show a chronological log of all recent actions
team compare [<ref1> | <ref1> <ref2>]  # Describe the differences between two updates (default: most recent vs previous)
team view [<ref>]                      # View team content for a specific update

Advanced

team combine <source> <target>  # Apply changes from one variant into another (merge)
team tidy                       # Clean up unused data to free up storage space
team stats                      # Show team size and update counts

How does Gitto work (for the nerds)?

Gitto borrows ideas from Git:

• Content-addressed storage
• SHA-1 hashing
• Merkle DAG data structure
• Lightweight branching via variants

But simplifies things:

• No staging area
• No files, just team snapshots
• Fully local

How do I report a bug?

If you run into a problem, please open an issue on GitHub: https://github.com/SaiNikhilTadepalli/Gitto/issues

When reporting a bug, please include:

• What you were trying to do
• The exact command(s) you ran
• The full error message/output
• Your environment (OS, Python version)
• Steps to reproduce the issue

What's next for Gitto?

Gitto v0.1.0 is focused on getting the core version control workflow right. With that foundation in place, there's plenty of room to build on top.

Some planned improvements include:

• A more polished CLI experience using libraries like rich or textual
• A tagging system for teams
• Search functionality across all teams and variants (by Pokémon, tags or keywords)

Have an idea for Gitto?

Gitto needs to keep evolving. Suggestions and feedback from users are very welcome.

If you have an idea for a feature or improvement, please open an issue on GitHub: https://github.com/SaiNikhilTadepalli/Gitto/issues

You can suggest things like:

• new features
• usability improvements
• workflow ideas / examples

If possible, include:

• what you're trying to achieve
• why it would be useful
• how you imagine it working

Why is it called Gitto?

Because it's like Git but for Pokémon. Also, Ditto transforms, just like your teams do.