Metadata-Version: 2.4
Name: gkel
Version: 1.1.9
Summary: A Git-native VCS experience with safe undo/redo, workspace parking, secret auditing, repository doctor, and smart asset handling
Author: MemeViber
License: MIT
Keywords: git,version-control,github,vcs,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: assets
Requires-Dist: Pillow>=10; extra == "assets"
Provides-Extra: zstd
Requires-Dist: zstandard>=0.22; extra == "zstd"
Provides-Extra: all
Requires-Dist: Pillow>=10; extra == "all"
Requires-Dist: zstandard>=0.22; extra == "all"
Provides-Extra: dev
Requires-Dist: Pillow>=10; extra == "dev"
Requires-Dist: zstandard>=0.22; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file


# Gkel

**Gkel is a new VCS experience layer running on genuine Git**: the repository is still cloned, pushed, pulled, and opened on GitHub as normal, but daily operations are less confusing and make it harder to lose code.

```text
Git handles the object graph, packfile, merge engine, and network.
Gkel handles the UX, safety, undo/redo, workspace, and asset workflow.
```

## Key Points

- **No permanent staging area:** `gkel save` saves the entire workspace or a group of files directly.
- **Full operation undo/redo:** Restores both the branch head and unsaved files.
- **Smart move:** Automatically parks unfinished work for each line and restores it upon return.
- **Stable Change-ID:** amending/rewriting still preserves the logical identity of the change.
- **Checkpoint:** Named workspace snapshots without creating a commit on the branch.
- **Git/GitHub-native:** Standard `.git`, standard remotes, standard Git LFS.
- **Layered compression:** Source code uses Git delta packing; images use a lossless optimizer; large binaries use LFS; backups use Git bundle + Zstandard.
- **Guard:** Blocks common private keys/tokens and files exceeding GitHub limits before saving/publishing.
- **Doctor:** Checks Git/object database/files/paths, scans API keys in the workspace, index, HEAD, and history; cleans caches safely.
- **Conflict UX:** Enables `rerere`, `zdiff3`, and provides `resolve`, `continue`, `abort` commands.

## Requirements

- Python 3.10+
- Git 2.35+ on `PATH` (newer versions recommended)
- Optional: Pillow for image optimization, Git LFS for large files, `zstd` or the `zstandard` package for `.gkelz`

## Installation

From PyPI:

```bash
python -m pip install gkel[all]
```

From Github:

```bash
python -m pip install git+https://github.com/memeviber/gkel.git
```

Install additional image/zstd support after installing the wheel:

```bash
python -m pip install Pillow zstandard
```

From source:

```bash
python -m pip install -e '.[dev]'
```

## Getting Started

```bash
mkdir demo
cd demo
gkel init

git config user.name "Your Name"
git config user.email "you@example.com"

echo hello > hello.txt
gkel status
gkel save -m "initial version"
```

This is genuine Git:

```bash
git log --oneline
git status
```

## Save Without Staging

Save the entire workspace:

```bash
gkel save -m "implement parser"
```

Save a specific group of paths, leaving other modifications in the workspace:

```bash
gkel save -m "parser only" src/parser.py tests/test_parser.py
```

Gkel uses an internal temporary index. If the real Git staging area contains data, the command will halt to avoid losing staged-only content:

```bash
gkel unstage
```

## Picking Specific Changes Safely

```bash
gkel pick P6e32d561a0
```

Gkel automatically creates a safety checkpoint before cherry-picking a specific Change-ID or commit to prevent data loss if merge conflicts occur.

If the pick fails or causes unwanted modifications, you can restore your pre-pick workspace:

```bash
gkel checkpoint restore before-pick-P6e32d561a
```

## Squashing History Safely

```bash
gkel squash
```

Gkel squashes the current commit into the previous one, cleanly merging their commit messages while automatically preserving the stable Change-ID of the parent.

## Reverting Historical Changes Safely

```bash
gkel revert P6e32d561a0
```

Gkel automatically creates a safety checkpoint before reverting a specific Change-ID or commit to prevent data loss if merge conflicts occur.

If the revert fails or causes unwanted modifications, you can restore your pre-revert workspace:

```bash
gkel checkpoint restore before-revert-P6e32d561a
```


## Discarding Workspace Changes Safely

```bash
gkel kill
```

Gkel captures a safety snapshot before running Git's destructive `reset --hard` and `clean -fd`.

If you regret discarding your work, simply run `gkel undo` to restore all deleted and modified files.

To permanently wipe the workspace without creating a safety backup:

```bash
gkel kill --no-backup
```

## Undo, Redo, and Timeline

```bash
gkel undo
gkel redo
gkel timeline
```

Undoing a `save` rolls the branch back to the previous commit while restoring the files to their state prior to the save. Undo only runs if the branch, workspace, and parked-workspace metadata have not been modified outside of Gkel.

Keep the 100 most recent operations and then clean objects that are no longer anchored:

```bash
gkel gc --keep-operations 100
```

## Lines and Dedicated Workspaces

```bash
gkel line create feature
gkel line move feature
```

If the current line has unsaved files, Gkel automatically parks them. Upon return:

```bash
gkel line move main
```

the workspace for `main` automatically returns. No manual stashing is required.

Create a line and switch immediately:

```bash
gkel line move -c experiment
```

List all lines, showing upstream tracking and parked workspaces:

```bash
gkel line list
```

## Checkpoints Without Dirtying History

```bash
gkel checkpoint create before-refactor
gkel checkpoint list
gkel checkpoint restore before-refactor
gkel checkpoint drop before-refactor
```

Checkpoint restorations are also undoable/redoable.

## GitHub

Connect using shorthand:

```bash
gkel connect owner/repository
# or SSH
gkel connect owner/repository --ssh
```

Publish the current line:

```bash
gkel publish
```

Create and manage tag markings safely:

```bash
gkel tag create v1.0.0
gkel tag list
```

Create an annotated tag and publish it to the remote immediately:

```bash
gkel tag create v1.0.0 -m "release version 1.0.0" --publish
```

Delete a tag locally and automatically sync the deletion to the remote:

```bash
gkel tag delete v1.0.0
```

Sync using fetch + rebase, backed by a safety snapshot:

```bash
gkel sync
```

Authentication is still handled by the Git credential helper, SSH agent, or GitHub tooling on the machine. Gkel does not store custom tokens.

## Merge and Conflict

```bash
gkel merge feature
gkel resolve src/conflicted.py
gkel continue
# or
gkel abort
```

Gkel enables Git `rerere` to remember previously resolved conflicts and uses `zdiff3` to display additional base context.

## Source Code Compression

Do not gzip/zstd individual source files: doing so breaks diffs and delta reuse. Instead:

```bash
gkel optimize --mode max
```

The command configures a high compression level and then repacks using a large delta window/depth, creating bitmaps, multi-pack indexes, and commit-graph changed-path data.

## Images and Large Files

View assets:

```bash
gkel asset scan
```

Configure LFS for common raw designs/videos/archives:

```bash
gkel asset lfs
```

Or with custom patterns:

```bash
gkel asset lfs '*.psd' '*.mp4' '*.tiff'
```

Lossless/pixel-lossless recompression, only replacing the file if the size is smaller:

```bash
gkel asset optimize assets/logo.png assets/hero.webp
```

Create new WebP or AVIF files:

```bash
gkel asset optimize assets/hero.png --target webp --lossy --quality 82
gkel asset optimize assets/diagram.png --target avif
```

The PNG optimizer attempts to preserve common ICC, EXIF, DPI, and text metadata. JPEG only runs the lossless optimizer if `jpegtran` is available; Gkel does not silently re-encode JPEGs and call it lossless.

## High-Ratio Backup

```bash
gkel bundle create project.gkelz
gkel bundle verify project.gkelz
gkel bundle clone project.gkelz restored-project
```

By default, the bundle is a complete Git bundle compressed with Zstandard level 19. You can also use:

```bash
gkel bundle create project.bundle.gz --compression gzip
gkel bundle create project.bundle --compression none
```

## Guard

> [!Warning]
> The built-in `guard` is designed as a fast, lightweight preflight check and may occasionally miss some credentials. For cryptographically guaranteed and comprehensive secret scanning of your repository, using specialized security tools like `gitleaks` is highly recommended.

```bash
gkel guard
gkel guard --all
```

`tag`, `save` and `publish` invoke the guard by default. The guard looks for private-key headers, common tokens/API keys, credentials embedded in URLs, sensitive-looking high-entropy assignments, and large files. This is a helpful preflight check, not a cryptographically guaranteed secret scanner.

## Doctor: Auditing, Secret Scanning, and Cleanup

> [!Warning]
> Both `gkel doctor` and `guard` are lightweight, fast preflight audits and may occasionally miss complex secrets. For comprehensive, cryptographically guaranteed historical scanning of sensitive credentials, using a specialized security scanner like `gitleaks` is highly recommended.

Quickly diagnose the repository, all version-controllable files, staged content, and the `HEAD` version when it differs from the workspace:

```bash
gkel doctor
```

Doctor checks:

- Git, author identity, workspace, staging, remote, Git LFS, and the object database.
- Gkel JSON metadata and stale locks.
- API keys/tokens/private keys in tracked, untracked, and sensitive ignored files such as `.env`, `.npmrc`, `.pypirc`, `*.pem`, `*.key`.
- Secrets sitting in the Git index even if the working files have been corrected.
- Secrets in the `HEAD` commit even if the workspace has deleted them.
- Remote URLs containing embedded usernames/tokens; URLs and secret values are not printed.
- Case/Unicode path collisions, non-portable names on Windows, broken symlinks or symlinks pointing outside the repo, unresolved conflict markers, and files exceeding GitHub limits.
- Verbatim appearances of sensitive environment variables in the source, without printing the actual values in the report.

Deep-scan all objects still reachable by refs or the reflog and run a full Git `fsck`:

```bash
gkel doctor --deep
gkel doctor --deep --history-budget-mib 512
```

Deep scanning has byte/object limits to prevent freezing on extremely large monorepos; the report will explicitly state when limited.

Preview what can be cleaned:

```bash
gkel doctor --clean --dry-run
```

Clean reproducible caches (`__pycache__`, `.pytest_cache`, `.mypy_cache`, swap files, Gkel temp), prune old worktree/rerere metadata, and run `git gc --auto`:

```bash
gkel doctor --clean
```

Only when `--aggressive` is explicitly specified will Doctor delete build output, virtual environments, or dependency caches; these types of items must be currently ignored by Git and must not contain tracked files:

```bash
gkel doctor --clean --aggressive
```

Use in CI:

```bash
gkel doctor --deep --strict --json > gkel-doctor.json
```

The exit code is `2` on critical errors/secrets, `1` on warnings when `--strict` is enabled, and `0` when there are no blocking errors. Doctor does not automatically delete source files or standard untracked files.

## Other Commands

```bash
gkel amend -m "better message"
gkel log -n 20
gkel why src/parser.py --line 42
gkel remote
gkel doctor --clean --dry-run
```

## Safety Limitations to Keep in Mind

- Snapshots do not contain ignored files. Doctor proactively scans sensitive ignored filenames, but does not search every file in `.venv`/`node_modules`; local secrets should still be managed via a secret manager and backed up securely.
- A normal `publish` cannot undo remote changes; `undo` only manages local Gkel operations.
- Gkel depends on the Git executable, so the final behavior of authentication, hooks, merge drivers, and the platform filesystem follows the local Git installation.
- Git LFS is an independent program. Gkel can write `.gitattributes`, but Git LFS must be installed before committing/pushing LFS objects.
- Asset conversion may require updating paths within your application; Gkel creates new files rather than automatically modifying source references.

## Development and Testing

```bash
python -m unittest discover -s tests -v
```

The test suite currently covers save/partial save, initial undo, amend identity, smart move, checkpoints, line lifecycles, merges, local-remote publish/clone/sync, blame, secret/large-file guards, Doctor workspace/index/HEAD/history scans, safe/aggressive cleanups, PNG optimization, LFS attributes, and zstd bundles.

See [DESIGN.md](https://github.com/memeviber/Gkel/blob/main/DESIGN.md) for detailed descriptions of object lifetimes, journal invariants, and compression decisions.
