Metadata-Version: 2.4
Name: shiggles
Version: 0.2.0
Summary: For git and shiggles. A simple content-addressed VCS.
Author: drLemis
License-Expression: LicenseRef-NWSL-1.0
Project-URL: Homepage, https://github.com/drLemis/shiggles
Project-URL: Repository, https://github.com/drLemis/shiggles
Project-URL: Issues, https://github.com/drLemis/shiggles/issues
Keywords: vcs,version-control,backup,sync
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Shiggles

Shiggles is a small command-line version control tool for people who want named saves, a simple history, and team sync without learning git.

It is designed for artists, designers, and small teams working on a shared project folder. You snapshot work with plain messages, switch context with tabs, and push or pull from a shared folder or HTTP URL.

[![License: NWSL](https://img.shields.io/badge/license-NWSL-orange)](https://github.com/ErikMcClure/bad-licenses/blob/master/NWSL)

Repository: [github.com/drLemis/shiggles](https://github.com/drLemis/shiggles)

## Features

- Watches a project folder and stores content-addressed snapshots on save.
- Named saves with author and time on each tab.
- Tabs for parallel work (`main` plus side piles like `hotfix`).
- `bring` lands your current tab into another tab (usually `main`).
- `upload` and `download` sync the current tab via shared folder or HTTP URL.
- Hard-stop collisions: conflicting files are parked in `.shig/collisions/` with next-step help.
- `load` restores an older save and makes it current.
- `undo` discards unsaved edits and reloads the last save.
- `timeline` append-only log of operations (including remote history after sync).
- Stdlib only. No git dependency.

## How It Works

When you run `shig start`, Shiggles creates a `.shig/` folder next to your project files. Each `shig save "message"` stores a snapshot of tracked files on the **current tab**.

Tabs keep separate histories. `main` is the default shared line. `shig tab foobar` forks from your current tab and switches you to a side pile.

Team sync copies commit objects, tab refs, tab metadata, and `timeline.log` to a remote. After `download`, files and history match what was uploaded from the other machine.

## Requirements

- Python 3.9 or newer
- Windows, macOS, or Linux

Optional for HTTP remotes: any host that can serve PUT/GET (or `scripts/shig-server.py` for local testing).

## Installation

**Windows (recommended):**

```powershell
.\install.ps1
```

Restart your terminal, then `shig help`.

**From PyPI** (after publish):

```bash
pip install shiggles
```

**Developers:**

```bash
pip install -e ".[dev]"
```

## Usage

1. Open a terminal in your project folder.
2. Run `shig start`.
3. Run `shig save "first version"`.
4. Use `shig changes` and `shig history` to see what changed.
5. Use `shig upload <path-or-url>` when you want to share with the team.

Basic solo workflow:

```bash
shig start
shig save "first version"
shig changes
shig history
```

### Tabs

- `main` - default tab, the shared project line
- `foobar` - your side pile for interrupted work

```bash
shig tab foobar       # create and switch
shig save "WIP window fix"
shig tab main         # switch back
shig tab foobar       # resume; files as you left them
```

### Team sync

**Shared folder** (NAS, network path, USB):

```bash
shig download \\NAS\projects\my-game
shig save "updated level"
shig upload
```

**HTTP URL** (optional token in `.shig/config.json`):

```bash
shig upload http://backup.example.com/shiggles/my-project
shig download
```

The remote is remembered in `.shig/config.json` after the first use.

If someone else saved while you were working, `shig save` nudges you to `download` first. Skip with `shig save --yes "message"`.

### Bring (landing your tab on main)

```bash
shig tab foobar
shig save "fixed shoot.cs"
shig bring main
```

If someone else changed the same file on `main`, Shiggles stops and prints next steps. Fix on **main**, not another `bring`.

### Restoring older work

- `shig load "message"` - put files back to a matching save (becomes current)
- `shig undo` - discard unsaved changes and reload the last save on this tab

## Commands

| Command | What it does |
|---------|--------------|
| `shig start` | Set up this folder |
| `shig save "..."` | Snapshot current tab |
| `shig save --yes "..."` | Save even if remote is ahead |
| `shig load "..."` | Put files back to a save (becomes current) |
| `shig changes` | What is different since last save |
| `shig history` | Saves on current tab |
| `shig tab [name]` | List, switch, or create tabs |
| `shig untab <name>` | Remove a tab (history kept) |
| `shig bring <tab>` | Land current tab into another |
| `shig download [path\|url]` | Pull current tab from remote |
| `shig upload [path\|url]` | Push current tab to remote |
| `shig undo` | Discard unsaved changes; back to last save |
| `shig timeline` | Operation log |

## Ignore files

Edit `.shignore` (created on `shig start`). Same idea as `.gitignore`. Build output, `.shig/`, and junk stay out of snapshots.

## Project structure

```text
shiggles/
  shiggles/           Python package (commands, store, remote sync)
  scripts/
    shig-server.py    Minimal HTTP remote for local testing
  tests/
    test_scenarios.py Scenario walkthrough and unit tests
  install.ps1         Windows installer
  LICENSE             NWSL-1.0
```

On-disk repo layout:

```text
.shignore
.shig/
  objects/
  refs/tabs/
  tabs/
  collisions/
  HEAD
  config.json
  timeline.log
```

## HTTP dev server

```bash
python scripts/shig-server.py ./remote-store -p 8765
shig upload http://127.0.0.1:8765
```

Use the full URL including `http://`. A bare `127.0.0.1:8765` is not recognized as HTTP.

## Tests

```bash
python tests/test_scenarios.py              # narrated walkthrough
python tests/test_scenarios.py --keep       # keep files in tests/_sandbox/
python tests/test_scenarios.py --clean      # wipe sandbox
python -m unittest discover -s tests -v     # unit tests
```

## Publish to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## Notes

- Shiggles is a simple VCS helper, not a replacement for full backups, cloud sync, or git power workflows.
- Collisions never overwrite your working files; compare copies under `.shig/collisions/`.
- See [ROADMAP.md](ROADMAP.md) for philosophy, collision policy, and deferred features.

## License

This software is licensed under the **[NWSL](https://github.com/ErikMcClure/bad-licenses/blob/master/NWSL)**.

Copyright (c) 2026 drLemis.
