From 88b41e6af67bb684708133975512242c4ce9a7ce Mon Sep 17 00:00:00 2001 From: Vincent Date: Thu, 21 May 2026 02:36:16 -0400 Subject: [PATCH] docs: rename reset command to restore (keep reset alias) --- docs/commands/diff.md | 2 +- docs/commands/insert.md | 2 +- docs/commands/overview.md | 8 +- docs/commands/push.md | 2 +- docs/commands/repository-management.md | 16 +- docs/commands/reset.md | 430 --------------------- docs/commands/restore.md | 205 ++++++++++ docs/commands/revise.md | 2 +- docs/commands/stash.md | 2 +- docs/commands/status.md | 6 +- docs/getting-started/migrating-from-git.md | 6 +- sidebars.ts | 2 +- 12 files changed, 229 insertions(+), 454 deletions(-) delete mode 100644 docs/commands/reset.md create mode 100644 docs/commands/restore.md diff --git a/docs/commands/diff.md b/docs/commands/diff.md index db78e0c..34488c5 100644 --- a/docs/commands/diff.md +++ b/docs/commands/diff.md @@ -456,7 +456,7 @@ context = "white" - [`atomic add`](./add.md) - Add files to track their changes - [`atomic change`](./change.md) - View diffs of recorded changes - [`atomic log`](./log.md) - View history of changes -- [`atomic reset`](./reset.md) - Discard working copy changes +- [`atomic restore`](./restore.md) - Discard working copy changes ## Related Concepts diff --git a/docs/commands/insert.md b/docs/commands/insert.md index bcf995f..2d888cb 100644 --- a/docs/commands/insert.md +++ b/docs/commands/insert.md @@ -254,7 +254,7 @@ Because Atomic uses a single canonical GRAPH with view filters, inserting a chan - **Dependencies**: Transitive dependencies are computed and inserted automatically. A change cannot be inserted without every change it depends on already present in the target view. - **Idempotent**: Inserting a change that already exists in the view is a no-op. - **Source unchanged**: The source view is never modified by an insert operation. -- **Working copy**: Use `atomic reset` after insert to update the working copy if needed. +- **Working copy**: Use `atomic restore` after insert to update the working copy if needed. - **Conflicts**: True conflicts only arise when changes modify the same graph region in incompatible ways. ## See Also diff --git a/docs/commands/overview.md b/docs/commands/overview.md index c0298a5..52eb853 100644 --- a/docs/commands/overview.md +++ b/docs/commands/overview.md @@ -24,7 +24,7 @@ Every command listed here corresponds to a real subcommand in the `atomic` CLI b | [`log`](log.md) | Show change history | | [`change`](change.md) | Inspect a specific change | | [`insert`](insert.md) | Insert changes into a view | -| [`reset`](reset.md) | Reset working copy to last recorded state | +| [`restore`](restore.md) | Restore working copy to last recorded state | | [`split`](split.md) | Create a new view from an existing one | | [`view`](view.md) | Manage views (create, switch, list, delete) | | [`stash`](stash.md) | Temporarily save uncommitted changes | @@ -66,17 +66,17 @@ atomic log # View history ### Repository Management -Create, clone, and reset repositories: +Create, clone, and restore repositories: ```bash atomic init myproject # Create a new repo atomic clone https://... # Clone from remote -atomic reset --force # Discard uncommitted changes +atomic restore --force # Discard uncommitted changes ``` - **[`init`](init.md)** — Initialize a new Atomic repository - **[`clone`](clone.md)** — Clone an existing repository from a remote -- **[`reset`](reset.md)** — Reset the working copy to the last recorded state +- **[`restore`](restore.md)** — Restore the working copy to the last recorded state - **[`split`](split.md)** — Create a new view from an existing one ### Views diff --git a/docs/commands/push.md b/docs/commands/push.md index 2a82783..67c5074 100644 --- a/docs/commands/push.md +++ b/docs/commands/push.md @@ -409,7 +409,7 @@ atomic push Or push from a clean state: ```bash -atomic reset +atomic restore atomic push ``` diff --git a/docs/commands/repository-management.md b/docs/commands/repository-management.md index 8fb4734..bbc580f 100644 --- a/docs/commands/repository-management.md +++ b/docs/commands/repository-management.md @@ -13,7 +13,7 @@ Commands for creating, cloning, and managing Atomic repositories. |---------|-------------| | [`init`](init.md) | Initialize a new Atomic repository | | [`clone`](clone.md) | Clone an existing repository from a remote | -| [`reset`](reset.md) | Reset working copy to the last recorded state | +| [`restore`](restore.md) | Restore working copy to the last recorded state | | [`split`](split.md) | Create a new view from an existing one | ## Creating a Repository @@ -52,19 +52,19 @@ atomic clone https://api.atomic.dev/acme/platform/core/code atomic clone https://api.atomic.dev/acme/platform/core/code myproject ``` -## Resetting the Working Copy +## Restoring the Working Copy -The `reset` command discards uncommitted changes and restores the working copy to the last recorded state: +The `restore` command discards uncommitted changes and restores the working copy to the last recorded state (the legacy name `reset` still works as an alias): ```bash # Discard all uncommitted changes -atomic reset --force +atomic restore --force -# Reset specific files -atomic reset src/main.rs +# Restore specific files +atomic restore src/main.rs -# Preview what would be reset -atomic reset --dry-run +# Preview what would be restored +atomic restore --dry-run ``` ## Splitting Views diff --git a/docs/commands/reset.md b/docs/commands/reset.md deleted file mode 100644 index 6531ebc..0000000 --- a/docs/commands/reset.md +++ /dev/null @@ -1,430 +0,0 @@ ---- -sidebar_position: 14 -title: reset ---- - -# atomic reset - -Reset the working copy to the last recorded state or switch views. - -## Synopsis - -```bash -atomic reset [OPTIONS] [FILES]... -``` - -## Description - -The `reset` command restores the working copy to match the pristine state (the last recorded state in the view). This is useful for: - -- **Discarding uncommitted changes**: Remove modifications you don't want to keep -- **Switching views**: Change to a different view and update the working copy -- **Restoring specific files**: Reset individual files while keeping others modified -- **Recovering from conflicts**: Reset to a clean state after problematic changes - -When you reset, Atomic: - -1. Compares the working copy with the pristine state -2. Restores files to match the view state -3. Discards any unrecorded modifications (unless `--force` is required) -4. Optionally switches the current view - -**Warning**: Reset discards uncommitted changes. They cannot be recovered unless recorded first. - -## Arguments - -### `[FILES]...` - -Optional paths to reset. If provided, only these files/directories are reset. If omitted, the entire working copy is reset. - -```bash -# Reset specific file -atomic reset src/main.rs - -# Reset directory -atomic reset src/ - -# Reset multiple files -atomic reset file1.txt file2.txt src/ -``` - -## Options - -### `--repository ` - -Specify the repository path if not running from within the repository directory. - -```bash -atomic reset --repository /path/to/repo -``` - -### `--view ` - -Reset the working copy to a specific view and switch to that view. - -```bash -# Switch to main view -atomic reset --view main - -# Switch to feature branch -atomic reset --view feature-new-ui -``` - -### `--dry-run` - -Print a file to standard output without modifying the repository. Works for a single file only. - -```bash -# Preview what file would look like after reset -atomic reset --dry-run src/main.rs - -# Pipe to viewer -atomic reset --dry-run README.md | less -``` - -### `-f, --force` - -Reset even if there are unrecorded changes. Required when discarding modifications. - -```bash -# Force reset with uncommitted changes -atomic reset --force - -# Force reset specific file -atomic reset --force src/main.rs -``` - -## Examples - -### Discard All Uncommitted Changes - -```bash -# Preview changes that would be lost -atomic diff - -# Discard all changes -atomic reset --force -``` - -### Reset Specific Files - -```bash -# Reset single file -atomic reset src/main.rs - -# Reset directory -atomic reset tests/ - -# Reset multiple specific files -atomic reset Cargo.toml README.md src/lib.rs -``` - -### Switch Views - -```bash -# Switch to main view -atomic reset --view main - -# Switch to feature view and reset working copy -atomic reset --view feature-auth -``` - -### Preview File Contents - -```bash -# Preview what a file would look like after reset -atomic reset --dry-run src/config.rs - -# Compare with current version -atomic reset --dry-run src/config.rs > /tmp/pristine.rs -diff src/config.rs /tmp/pristine.rs -``` - -### Safe Reset Workflow - -```bash -# Check what would be lost -atomic diff - -# Optionally save work-in-progress -atomic record -m "WIP: save current state" - -# Now reset safely -atomic reset --force - -# Or revert to the WIP change later -atomic unrecord # if needed -``` - -## Reset vs. Other Commands - -### Reset vs. Unrecord - -- **`reset`**: Discards working copy changes, doesn't affect recorded history -- **`unrecord`**: Removes changes from view history, preserves working copy - -```bash -# Discard uncommitted changes -atomic reset --force - -# Remove last recorded change -atomic unrecord -``` - -### Reset vs. Revert - -Atomic doesn't have a "revert" command because changes can be unrecorded: - -```bash -# To undo a recorded change: -atomic unrecord HASH... -atomic reset --force # Update working copy -``` - -## View Switching - -When using `--view` to switch views: - -### Without Uncommitted Changes - -```bash -# Clean switch -atomic reset --view feature-branch -``` - -Atomic will: -1. Switch the current view -2. Update working copy to match the new view -3. Complete without warnings - -### With Uncommitted Changes - -```bash -# Attempt to switch with changes -atomic reset --view main -# Error: Cannot change view, as there are unrecorded changes. -``` - -Solution: -```bash -# Option 1: Record changes first -atomic record -m "Save changes" -atomic reset --view main - -# Option 2: Force discard changes -atomic reset --force --view main -``` - -### Partial View Difference - -If views have diverged, reset updates only affected files: - -```bash -# Switch to view with different files -atomic reset --view experimental - -# Only files that differ between views are updated -# Other files remain unchanged -``` - -## Reset Behavior - -### Full Reset (No Files Specified) - -```bash -atomic reset --force -``` - -Restores the entire working copy: -- Modified files are reverted -- Added files (untracked) remain -- Tracked files are restored to pristine state - -### Partial Reset (Files Specified) - -```bash -atomic reset src/main.rs -``` - -Only specified files are reset: -- Other modifications remain intact -- Only listed files/directories are restored - -### Dry Run - -```bash -atomic reset --dry-run file.txt > /tmp/pristine.txt -``` - -- Doesn't modify any files -- Outputs pristine version to stdout -- Works for exactly one file -- Useful for previewing changes - -## Configuration - -Relevant configuration options: - -```toml -# In .atomic/config.toml or ~/.config/atomic/config.toml - -# Control reset behavior with changes -reset_overwrites_changes = "auto" # "auto", "always", or "never" -``` - -Options: -- `"never"` - Always require `--force` to discard changes -- `"auto"` or `"always"` - Allow reset to discard changes without `--force` (default) - -## Performance - -Reset performance depends on: - -- **Working copy size**: More files = longer reset -- **Number of files to reset**: Fewer files = faster -- **View differences**: Bigger differences = more work - -Typical reset times: -- **Small reset** (< 10 files): < 100ms -- **Medium reset** (10-100 files): < 1 second -- **Full reset** (entire repository): 1-10 seconds - -## Use Cases - -### Experimenting Safely - -```bash -# Make experimental changes -vim src/experimental.rs - -# Test them -cargo test - -# Discard if they don't work -atomic reset --force -``` - -### Recovering from Mistakes - -```bash -# Accidentally modified many files -atomic diff # Oh no, too many changes! - -# Reset to clean state -atomic reset --force -``` - -### Cleaning Up Merge Conflicts - -```bash -# After pull, conflicts appear -atomic pull -# Warning: Conflicts detected - -# Reset to pre-pull state -atomic reset --force - -# Or reset just conflicted files -atomic reset src/conflicted.rs -``` - -### File Recovery - -```bash -# Accidentally deleted a file -rm important.txt - -# Recover it -atomic reset important.txt -``` - -## Conflicts After Reset - -In rare cases, reset might produce conflicts in the working copy: - -``` -Warning: Conflicts detected in working copy - - src/main.rs -``` - -This happens when: -- View has conflicting changes -- Working copy state is complex - -Resolution: -```bash -# View conflicts -atomic diff - -# Manually resolve -vim src/main.rs - -# Record resolution -atomic record -m "Resolve conflicts" -``` - -## Notes - -- **Destructive**: Reset discards uncommitted changes permanently -- **Working Copy Only**: Doesn't affect recorded history -- **Selective**: Can reset individual files -- **View Switching**: Updates working copy when changing views -- **Safe by Default**: Warns before discarding changes (unless configured otherwise) -- **Dry Run**: Preview changes without modifying files - -## Best Practices - -### Always Check First - -```bash -# Review what will be lost -atomic diff - -# Then reset -atomic reset --force -``` - -### Save Important Work - -```bash -# If unsure, record first -atomic record -m "WIP: experimental changes" - -# Now safe to reset -atomic reset --force - -# Can unrecord later if needed -atomic unrecord -``` - -### Selective Reset - -```bash -# Reset only what's needed -atomic reset src/broken_module.rs - -# Keep other changes -atomic diff # Shows remaining modifications -``` - -## Exit Codes - -- `0` - Success -- `1` - Error (no view, conflicts, etc.) -- `2` - Invalid arguments - -## See Also - -- [`atomic diff`](./diff.md) - Preview changes before resetting -- [`atomic revise`](./revise.md) - Revise a recorded change -- [`atomic record`](./record.md) - Record changes before resetting -- [`atomic view`](./view.md) - View management -- [`atomic insert`](./insert.md) - Insert specific changes - -## Related Concepts - -- **Working Copy** - Your editable files on disk -- **Pristine** - The recorded repository state -- **Views** - Independent lines of development -- **Uncommitted Changes** - Modifications not yet recorded -- **Destructive Operation** - Cannot be undone \ No newline at end of file diff --git a/docs/commands/restore.md b/docs/commands/restore.md new file mode 100644 index 0000000..df0a5bf --- /dev/null +++ b/docs/commands/restore.md @@ -0,0 +1,205 @@ +--- +sidebar_position: 14 +title: restore +--- + +# atomic restore + +Restore the working copy to the last recorded state. + +`atomic restore` is the working-copy counterpart of `git restore`: it discards +unrecorded edits and brings files back to the pristine state (the last recorded +state in the current view). + +:::note Renamed from `reset` +This command was previously called `atomic reset`. The old name still works as +an alias, so existing scripts keep running, but `atomic restore` is the +canonical name. Switching views is a separate command — see +[`atomic view switch`](./view.md). +::: + +## Synopsis + +```bash +atomic restore [OPTIONS] [FILES]... +``` + +## Description + +The `restore` command restores the working copy to match the pristine state. +This is useful for: + +- **Discarding uncommitted changes**: Remove modifications you don't want to keep +- **Restoring specific files**: Restore individual files while keeping others modified +- **Recovering deleted files**: Bring back a tracked file you removed on disk + +When you restore, Atomic: + +1. Compares the working copy with the pristine state +2. Restores files to match the last recorded state +3. Discards any unrecorded modifications + +**Warning**: Restore discards uncommitted changes. They cannot be recovered +unless recorded first. + +## Arguments + +### `[FILES]...` + +Optional paths to restore. If provided, only these files/directories are +restored. Naming files is explicit consent to discard their changes, so no +`--force` is needed. If omitted, the entire working copy is restored, which +requires `--force`. + +```bash +# Restore a specific file +atomic restore src/main.rs + +# Restore a directory +atomic restore src/ + +# Restore multiple files +atomic restore file1.txt file2.txt src/ +``` + +## Options + +### `--dry-run` + +Print a file to standard output without modifying the repository. Works for a +single file only. + +```bash +# Preview what a file would look like after restore +atomic restore --dry-run src/main.rs + +# Pipe to viewer +atomic restore --dry-run README.md | less +``` + +### `-f, --force` + +Required only for a whole-tree restore (no files named), because it discards +*all* uncommitted changes at once. + +```bash +# Discard every uncommitted change +atomic restore --force +``` + +## Examples + +### Discard a single file's changes + +```bash +atomic restore src/main.rs +``` + +### Discard all uncommitted changes + +```bash +# Preview changes that would be lost +atomic diff + +# Discard all changes +atomic restore --force +``` + +### Recover a deleted file + +```bash +# Accidentally deleted a tracked file +rm important.txt + +# Bring it back +atomic restore important.txt +``` + +### Preview file contents + +```bash +# Preview what a file would look like after restore +atomic restore --dry-run src/config.rs > /tmp/pristine.rs +diff src/config.rs /tmp/pristine.rs +``` + +## Behavior by file state + +`restore` only touches tracked, dirty files. Untracked files are never touched. + +| File state | What `restore` does | +| --- | --- | +| Modified | Reverts content to the pristine version | +| Deleted (on disk) | Recreates the file from pristine | +| Added (tracked, not recorded) | Undoes tracking; the file stays on disk as untracked | +| Untracked | Left alone — `restore` never deletes files you created | + +### Whole-tree vs. partial + +```bash +# Whole tree — discards all uncommitted changes (requires --force) +atomic restore --force + +# Partial — only the named paths; other modifications are kept +atomic restore src/main.rs +``` + +A partial restore is never blocked by unrelated dirty files: only the paths you +name are affected. + +## restore vs. other commands + +### restore vs. unrecord + +- **`restore`**: Discards working-copy changes; does not affect recorded history +- **`unrecord`**: Removes a change from view history; preserves the working copy + +```bash +# Discard uncommitted changes +atomic restore --force + +# Remove the last recorded change +atomic unrecord +``` + +### Undoing a recorded change + +Atomic has no "revert" command — recorded changes are removed with `unrecord`: + +```bash +atomic unrecord HASH... +atomic restore --force # update the working copy afterwards if needed +``` + +### Switching views + +`restore` does not switch views. Use [`atomic view switch`](./view.md), which +materializes the working copy for the target view. + +## Notes + +- **Destructive**: Restore discards uncommitted changes permanently +- **Working copy only**: Doesn't affect recorded history +- **Selective**: Can restore individual files +- **Keeps untracked files**: Never deletes files you created +- **Dry run**: Preview a single file's pristine content without modifying it + +## Exit Codes + +- `0` - Success +- `1` - Refused (e.g. whole-tree restore without `--force`) +- `2` - Invalid arguments + +## See Also + +- [`atomic diff`](./diff.md) - Preview changes before restoring +- [`atomic view`](./view.md) - Switch and manage views +- [`atomic record`](./record.md) - Record changes before restoring +- [`atomic unrecord`](./unrecord.md) - Remove a recorded change + +## Related Concepts + +- **Working Copy** - Your editable files on disk +- **Pristine** - The recorded repository state +- **Views** - Independent lines of development +- **Uncommitted Changes** - Modifications not yet recorded diff --git a/docs/commands/revise.md b/docs/commands/revise.md index 7768b98..6ae43d2 100644 --- a/docs/commands/revise.md +++ b/docs/commands/revise.md @@ -106,5 +106,5 @@ atomic revise @~1 --dry-run - [record](record.md) — Recording new changes - [log](log.md) — Viewing change history -- [reset](reset.md) — Discarding working copy changes +- [restore](restore.md) — Discarding working copy changes - [change](change.md) — Inspecting change details \ No newline at end of file diff --git a/docs/commands/stash.md b/docs/commands/stash.md index 73ce28c..fe1417a 100644 --- a/docs/commands/stash.md +++ b/docs/commands/stash.md @@ -201,5 +201,5 @@ atomic stash drop --all - [view](view.md) — Managing views - [record](record.md) — Recording changes -- [reset](reset.md) — Discarding working copy changes +- [restore](restore.md) — Discarding working copy changes - [status](status.md) — Viewing working copy status \ No newline at end of file diff --git a/docs/commands/status.md b/docs/commands/status.md index 0821422..404010d 100644 --- a/docs/commands/status.md +++ b/docs/commands/status.md @@ -91,7 +91,7 @@ On view main State: ABCD1234EFGH5678 Changes to be recorded: - (use "atomic reset ..." to discard changes) + (use "atomic restore ..." to discard changes) new file: src/new_feature.rs modified: src/main.rs @@ -139,7 +139,7 @@ On view main State: ABCD1234EFGH5678 Changes to be recorded: - (use "atomic reset ..." to discard changes) + (use "atomic restore ..." to discard changes) modified: src/main.rs @@ -366,7 +366,7 @@ enabled = "auto" - [`atomic diff`](./diff.md) - Show detailed content differences - [`atomic record`](./record.md) - Record changes after reviewing status - [`atomic add`](./add.md) - Add untracked files to tracking -- [`atomic reset`](./reset.md) - Discard working copy changes +- [`atomic restore`](./restore.md) - Discard working copy changes - [`atomic log`](./log.md) - View history of recorded changes ## Related Concepts diff --git a/docs/getting-started/migrating-from-git.md b/docs/getting-started/migrating-from-git.md index a895968..bba955e 100644 --- a/docs/getting-started/migrating-from-git.md +++ b/docs/getting-started/migrating-from-git.md @@ -269,7 +269,7 @@ git reset HEAD~1 git revert commit-hash # Atomic -atomic reset --force # Discard working copy changes +atomic restore --force # Discard working copy changes atomic unrecord # Remove recorded changes atomic unrecord CHANGE-HASH # Remove specific change ``` @@ -646,8 +646,8 @@ atomic git import **Problem**: Files look different after import ```bash -# Solution: Reset working copy -atomic reset --force +# Solution: Restore working copy +atomic restore --force ``` ### Remote Push Issues diff --git a/sidebars.ts b/sidebars.ts index a9a17fb..08284db 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -109,7 +109,7 @@ const sidebars: SidebarsConfig = { items: [ "commands/init", "commands/clone", - "commands/reset", + "commands/restore", "commands/split", ], },