update readme

Author: wbbradley

Cargo.lock

@@ -1,9 +1,9 @@
 [package]
 name = "git-stack"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2024"
 license = "GPL2"
-keywords = ["git", "stack", "vcs"]
+keywords = ["git", "stack", "github"]
 categories = ["development-tools"]
 description = "A git stacking CLI for basic stacked diff management."
 readme = "README.md"

Cargo.toml

@@ -1,119 +1,107 @@
 # git-stack
 
-`git-stack` is a command-line tool for managing stacked git branches — a workflow where you develop
-features atop one another, keeping their history clean and rebasing as needed. It tracks
-relationships between branches, helps you re-stack and synchronize them, and visualizes your stack
-tree.
-
-`git-stack` also allows for synchronization between Github and local state.
-
-## Key Features
-
-- Stacked Workflow: Track parent-child branch relationships ("stacks") in your repo.
-- Restack: Automatically rebase your branch stack on top of trunk or another branch.
-- Status Tree: Visualize your current stacked branches, their hierarchy, and sync status.
-- Branch Mounting: Change the parent branch of an existing branch in your stack.
-- Diffs: Show changes between a branch and its parent.
-- Safe Operations: Prevent accidental data loss by checking upstream sync status.
+A command-line tool for managing stacked git branches. Develop features on top of one another, keep history clean, and sync with GitHub.
 
 ## Installation
 
-Build from source (Rust required):
-
 ```bash
-cargo install --path .
+cargo install --git https://github.com/wbbradley/git-stack --locked
 ```
 
-This will install a CLI you can use as follows:
+## Quick Start
 
 ```bash
-git stack <command> [options]
+git stack                    # show your stack
+git stack sync               # sync local state with GitHub (push + pull)
+git stack checkout feature   # create branch "feature" as child of current branch
+# ...make changes, commit...
+git stack restack            # restack the current branch onto its parent
+git stack diff               # diff against parent branch
+git stack pr create          # create GitHub PR with correct base branch
 ```
 
-## Usage
+## Commands
 
-You can invoke `git-stack` directly or as a git subcommand:
+### View Your Stack
 
 ```bash
-git stack <subcommand> [options]
+git stack                    # show the stack tree (alias: git stack status)
 ```
 
-### Common Subcommands
-
-- `status`: Show the current stack tree in the repo.
-  - _Default_, so `git stack` is equivalent to `git stack status`.
-
-- `checkout <branch>`: Create a new branch stacked on the current branch, or checkout an existing
-  one in the stack.
-
-- `restack [--branch <branch>]`: Rebase the named (or current) branch and its descendents onto their
-  updated stack base (like trunk or a parent feature branch). This command recursively applies to
-  all ancestors of the given branch.
+### Create Branches
 
-- `mount [<parent-branch>]`: Mounts (attaches) the current branch on a different parent branch.
+```bash
+git stack checkout feature   # create "feature" stacked on current branch
+```
 
-- `diff [<branch>]`: Show diff between a branch and its stack parent.
+### Restack Branches
 
-- `delete <branch>`: Remove a branch from the stack tree.
+```bash
+git stack restack            # restack current branch onto its parent
+git stack restack -afp       # fetch, recursively restack from trunk, push on success
+```
 
-### Examples
+The `-afp` flags:
+- `-a` / `--ancestors`: recursively restack all ancestors from trunk up to current branch
+- `-f` / `--fetch`: fetch updates from remote first
+- `-p` / `--push`: push branch updates to remote on success
 
-#### See your stack status
+### Diff Against Parent
 
-```
-git stack status
+```bash
+git stack diff               # diff against parent branch
 ```
 
-#### Create and stack a new branch
+### Create Pull Requests
 
-```
-git stack checkout my-feature
+```bash
+git stack pr create          # create GitHub PR with correct base branch
 ```
 
-#### Restack your current branch
+### Change Parent Branch
 
-```
-git stack restack
+```bash
+git stack mount <parent>     # stack current branch on a different parent
 ```
 
-#### Change the parent stack of a feature branch
+This only updates git-stack metadata, not git history. Use `restack` afterward to keep this branch
+in sync with its parent.
 
-```
-git stack mount new-parent-branch
+### Delete Branches
+
+```bash
+git stack delete <branch>    # remove a branch from the stack
 ```
 
-#### Show diff with parent
+Note that `git stack sync` will automatically prune local branches that are duplicates of the remote
+branch, or have already been merged.
 
-```
-git stack diff my-feature
-```
+## Workflow Example
 
-#### Remove a branch from stack management
+```bash
+# Start on main
+git stack checkout auth      # create auth branch
+# ...implement auth, commit...
 
-```
-git stack delete my-feature
+git stack checkout login     # create login branch (child of auth)
+# ...implement login, commit...
+
+git stack                    # see your stack tree
+git stack restack -afp       # sync everything and push
+git stack pr create          # create PR for current branch
 ```
 
 ## Stack Storage
 
-- Stack state is stored per-repo in a YAML file at:
-  `~/.local/state/git-stack/state.yaml` (using XDG state dir conventions).
-
-## Requirements
-
-- A POSIX shell
-- git (on your `$PATH`)
-- Rust (to install/build)
+Stack state is stored per-repo in `~/.local/state/git-stack/state.yaml`.
 
 ## Troubleshooting
 
-If `git stack` reports missing branches or refuses to restack:
+If `git stack` reports issues:
 
-- Ensure your working tree is clean (`git status`).
-- Use standard git commands to resolve any rebase conflicts (`git mergetool` is your friend,
-  followed by `git rebase --continue`), then rerun `git stack restack`.
-- Note that the last-known-good location of the parent branch is stored in the sub-branch in order
-  to allow for cleaner movement of branches
+- Ensure your working tree is clean (`git status`)
+- Resolve rebase conflicts with standard git commands (`git mergetool`, then `git rebase --continue`)
+- Rerun `git stack restack` after resolving conflicts
 
 ## License