Skip to content

Commit d123345

Browse files
nickprotopnickprotop
committed
Add documentation for cloud log, revert, and snapshot commands
1 parent 2e51d91 commit d123345

6 files changed

Lines changed: 521 additions & 6 deletions

File tree

‎_lrm‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -546,6 +546,9 @@ _lrm() {
546546
'status:Show cloud sync status or account info'
547547
'push:Push local changes to cloud'
548548
'pull:Pull remote changes from cloud'
549+
'log:Show sync history (push/revert operations)'
550+
'revert:Revert a previous push (undo changes)'
551+
'snapshot:Snapshot management for point-in-time backups'
549552
'set-token:Manually set an authentication token'
550553
'set-api-key:Store a CLI API key for cloud authentication'
551554
'remote:Remote URL configuration'
@@ -634,6 +637,89 @@ _lrm() {
634637
'--remove[Remove stored API key]' \
635638
$global_opts
636639
;;
640+
log)
641+
_arguments \
642+
'1:history ID' \
643+
'(-n --number)'{-n,--number}'[Number of entries to show]:count:(10 20 50 100)' \
644+
'--page[Page number]:page' \
645+
'--oneline[Show compact one-line format]' \
646+
'(-f --format)'{-f,--format}'[Output format]:format:->formats' \
647+
$global_opts
648+
case $state in
649+
formats)
650+
_describe -t formats 'output formats' format_opts
651+
;;
652+
esac
653+
;;
654+
revert)
655+
_arguments \
656+
'1:history ID' \
657+
'(-m --message)'{-m,--message}'[Message describing the revert]:message' \
658+
'(-y --yes)'{-y,--yes}'[Skip confirmation prompt]' \
659+
'--dry-run[Preview without reverting]' \
660+
'(-f --format)'{-f,--format}'[Output format]:format:->formats' \
661+
$global_opts
662+
case $state in
663+
formats)
664+
_describe -t formats 'output formats' format_opts
665+
;;
666+
esac
667+
;;
668+
snapshot)
669+
local -a snapshot_subcommands
670+
snapshot_subcommands=(
671+
'list:List all snapshots'
672+
'create:Create a new snapshot'
673+
'show:Show snapshot details'
674+
'restore:Restore to a snapshot'
675+
'delete:Delete a snapshot'
676+
'diff:Compare two snapshots'
677+
)
678+
679+
_arguments -C \
680+
'1: :->snapshot_subcommand' \
681+
'*:: :->snapshot_subargs' \
682+
&& return 0
683+
684+
case $state in
685+
snapshot_subcommand)
686+
_describe -t snapshot-subcommands 'snapshot subcommands' snapshot_subcommands
687+
;;
688+
snapshot_subargs)
689+
case $words[1] in
690+
list)
691+
_arguments \
692+
'--page[Page number]:page' \
693+
'--page-size[Items per page]:size:(10 20 50)' \
694+
'(-f --format)'{-f,--format}'[Output format]:format:->formats' \
695+
$global_opts
696+
;;
697+
create)
698+
_arguments \
699+
'1:snapshot description' \
700+
'(-f --format)'{-f,--format}'[Output format]:format:->formats' \
701+
$global_opts
702+
;;
703+
show|restore|delete)
704+
_arguments \
705+
'1:snapshot ID' \
706+
$global_opts
707+
;;
708+
diff)
709+
_arguments \
710+
'1:from snapshot ID' \
711+
'2:to snapshot ID' \
712+
$global_opts
713+
;;
714+
esac
715+
case $state in
716+
formats)
717+
_describe -t formats 'output formats' format_opts
718+
;;
719+
esac
720+
;;
721+
esac
722+
;;
637723
remote)
638724
local -a remote_subcommands
639725
remote_subcommands=(

‎cloud/src/www/docs/cloud.html‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -912,6 +912,34 @@ <h3>Backup System</h3>
912912
<li>Restore manually: <code>unzip .lrm/pull-backups/backup.zip -d .</code></li>
913913
</ul>
914914

915+
<h3>History & Undo</h3>
916+
<p>View sync history and undo previous pushes:</p>
917+
<pre><code># View sync history
918+
lrm cloud log
919+
920+
# View more history entries
921+
lrm cloud log -n 20
922+
923+
# Undo a specific push
924+
lrm cloud revert abc12345
925+
926+
# Preview what would be reverted
927+
lrm cloud revert abc12345 --dry-run</code></pre>
928+
929+
<h3>Snapshots</h3>
930+
<p>Create named snapshots for important milestones (like Git tags):</p>
931+
<pre><code># Create a snapshot before major changes
932+
lrm cloud snapshot create "Before v2.0 release"
933+
934+
# List all snapshots
935+
lrm cloud snapshot list
936+
937+
# Restore to a previous snapshot
938+
lrm cloud snapshot restore &lt;snapshot-id&gt;
939+
940+
# Compare two snapshots
941+
lrm cloud snapshot diff &lt;from-id&gt; &lt;to-id&gt;</code></pre>
942+
915943
<div class="info-box">
916944
<div class="info-box-title">Full Documentation</div>
917945
<p>See the <a href="https://github.com/nickprotop/LocalizationManager/blob/main/docs/CLOUD_SYNC.md" target="_blank">Cloud Sync Guide</a> for complete CLI documentation.</p>

‎docs/CLOUD_SYNC.md‎

Lines changed: 210 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ The LRM CLI tool supports bidirectional synchronization with LRM Cloud, allowing
1515
- [Backup System](#backup-system)
1616
- [Configuration Sync](#configuration-sync)
1717
- [Advanced Usage](#advanced-usage)
18+
- [Log Command](#log-command)
19+
- [Revert Command](#revert-command)
20+
- [Snapshot Command](#snapshot-command)
21+
- [API Reference](#api-reference)
1822

1923
## Overview
2024

@@ -538,25 +542,215 @@ A: Yes, use `--no-backup`, but not recommended:
538542
lrm cloud pull --no-backup
539543
```
540544

545+
## Log Command
546+
547+
View the sync history for your project, showing all push and revert operations.
548+
549+
### Basic Usage
550+
551+
```bash
552+
# Show recent sync history (default: 10 entries)
553+
lrm cloud log
554+
555+
# Show more entries
556+
lrm cloud log -n 20
557+
558+
# Compact one-line format
559+
lrm cloud log --oneline
560+
561+
# View details of a specific history entry
562+
lrm cloud log abc12345
563+
564+
# JSON output for automation
565+
lrm cloud log --format json
566+
```
567+
568+
### Options
569+
570+
| Option | Description |
571+
|--------|-------------|
572+
| `[HISTORY_ID]` | Optional history ID to show details for a specific push |
573+
| `-n, --number <COUNT>` | Number of entries to show (default: 10) |
574+
| `--page <PAGE>` | Page number for pagination (default: 1) |
575+
| `--oneline` | Show compact one-line format |
576+
| `-f, --format <FORMAT>` | Output format: table (default), json, simple |
577+
578+
### Example Output
579+
580+
```
581+
Sync History
582+
┌──────────┬─────────────────────┬───────────┬─────────┬──────────┬─────────────────────┐
583+
│ ID │ Date │ Operation │ Added │ Modified │ Message │
584+
├──────────┼─────────────────────┼───────────┼─────────┼──────────┼─────────────────────┤
585+
│ abc12345 │ 2024-01-15 10:30:22 │ push │ 5 │ 12 │ Added translations │
586+
│ def67890 │ 2024-01-14 16:45:10 │ push │ 0 │ 3 │ Fixed typos │
587+
│ ghi11213 │ 2024-01-14 09:15:00 │ revert │ 0 │ 0 │ Revert: abc12345 │
588+
└──────────┴─────────────────────┴───────────┴─────────┴──────────┴─────────────────────┘
589+
```
590+
591+
## Revert Command
592+
593+
Undo a previous push by reverting to the state before that push.
594+
595+
### Basic Usage
596+
597+
```bash
598+
# Revert a specific push
599+
lrm cloud revert abc12345
600+
601+
# Revert with a message explaining why
602+
lrm cloud revert abc12345 -m "Rolling back broken translations"
603+
604+
# Preview what would be reverted (dry run)
605+
lrm cloud revert abc12345 --dry-run
606+
607+
# Skip confirmation prompt
608+
lrm cloud revert abc12345 -y
609+
```
610+
611+
### Options
612+
613+
| Option | Description |
614+
|--------|-------------|
615+
| `<HISTORY_ID>` | The history entry ID to revert (required) |
616+
| `-m, --message <MESSAGE>` | Message describing why the revert was done |
617+
| `-y, --yes` | Skip confirmation prompt |
618+
| `--dry-run` | Show what would be reverted without actually reverting |
619+
| `-f, --format <FORMAT>` | Output format: table (default), json, simple |
620+
621+
### Workflow
622+
623+
1. Use `lrm cloud log` to find the history ID of the push you want to undo
624+
2. Run `lrm cloud revert <HISTORY_ID> --dry-run` to preview changes
625+
3. If satisfied, run `lrm cloud revert <HISTORY_ID>` to perform the revert
626+
4. The revert creates a new history entry (visible in `lrm cloud log`)
627+
628+
## Snapshot Command
629+
630+
Create and manage point-in-time snapshots of your project. Snapshots are like named bookmarks in your project's history that you can restore to at any time.
631+
632+
### Subcommands
633+
634+
#### snapshot list
635+
636+
List all snapshots for the project:
637+
638+
```bash
639+
lrm cloud snapshot list
640+
lrm cloud snapshot list --page 2
641+
lrm cloud snapshot list --format json
642+
```
643+
644+
**Options:**
645+
- `--page <PAGE>` - Page number (default: 1)
646+
- `--page-size <SIZE>` - Items per page (default: 20)
647+
- `-f, --format <FORMAT>` - Output format: table (default), json, simple
648+
649+
#### snapshot create
650+
651+
Create a new snapshot of the current project state:
652+
653+
```bash
654+
# Create snapshot with auto-generated name
655+
lrm cloud snapshot create
656+
657+
# Create snapshot with description
658+
lrm cloud snapshot create "Before major refactor"
659+
```
660+
661+
**Options:**
662+
- `[message]` - Optional description for the snapshot
663+
664+
#### snapshot show
665+
666+
View details of a specific snapshot:
667+
668+
```bash
669+
lrm cloud snapshot show <snapshot-id>
670+
```
671+
672+
#### snapshot restore
673+
674+
Restore the project to a previous snapshot:
675+
676+
```bash
677+
lrm cloud snapshot restore <snapshot-id>
678+
```
679+
680+
**Warning:** This will overwrite your current project state with the snapshot's state.
681+
682+
#### snapshot delete
683+
684+
Delete a snapshot:
685+
686+
```bash
687+
lrm cloud snapshot delete <snapshot-id>
688+
```
689+
690+
#### snapshot diff
691+
692+
Compare two snapshots to see what changed:
693+
694+
```bash
695+
lrm cloud snapshot diff <from-snapshot-id> <to-snapshot-id>
696+
```
697+
698+
### When to Use Snapshots vs History
699+
700+
| Feature | Sync History (`log`/`revert`) | Snapshots |
701+
|---------|------------------------------|-----------|
702+
| Created | Automatically on each push | Manually by user |
703+
| Purpose | Track all changes | Mark important milestones |
704+
| Restore | Undo specific pushes | Restore entire project state |
705+
| Retention | May be pruned over time | Kept until deleted |
706+
707+
**Use Snapshots for:**
708+
- Before major refactoring
709+
- Release versions (v1.0, v2.0)
710+
- Before experimental changes
711+
- Milestone backups
712+
713+
**Use History/Revert for:**
714+
- Undoing recent mistakes
715+
- Reviewing what changed
716+
- Debugging sync issues
717+
541718
## API Reference
542719

543720
### Remote Commands
544721

545-
- `lrm remote set <url>` - Set remote URL
546-
- `lrm remote get` - Show current remote URL
547-
- `lrm remote unset` - Remove remote configuration
722+
- `lrm cloud remote set <url>` - Set remote URL
723+
- `lrm cloud remote get` - Show current remote URL
724+
- `lrm cloud remote unset` - Remove remote configuration
548725

549726
### Cloud Commands
550727

728+
**Project Setup:**
551729
- `lrm cloud clone <url> [path]` - Clone existing project (login + link + pull)
552730
- `lrm cloud init [url]` - Connect to cloud project (interactive or direct URL)
731+
732+
**Authentication:**
553733
- `lrm cloud login [host]` - Authenticate via email/password
554734
- `lrm cloud logout` - Clear stored tokens
735+
- `lrm cloud set-token [token]` - Set authentication token manually
736+
- `lrm cloud set-api-key [key]` - Store a CLI API key for authentication
737+
738+
**Sync Operations:**
555739
- `lrm cloud push [options]` - Push local changes to cloud
556740
- `lrm cloud pull [options]` - Pull remote changes from cloud
557741
- `lrm cloud status` - Show sync status or account info
558-
- `lrm cloud set-token [token]` - Set authentication token manually
559-
- `lrm cloud set-api-key [key]` - Store a CLI API key for authentication
742+
743+
**History & Recovery:**
744+
- `lrm cloud log [history_id]` - Show sync history
745+
- `lrm cloud revert <history_id>` - Revert a previous push
746+
747+
**Snapshots:**
748+
- `lrm cloud snapshot list` - List all snapshots
749+
- `lrm cloud snapshot create [message]` - Create a new snapshot
750+
- `lrm cloud snapshot show <id>` - View snapshot details
751+
- `lrm cloud snapshot restore <id>` - Restore to a snapshot
752+
- `lrm cloud snapshot delete <id>` - Delete a snapshot
753+
- `lrm cloud snapshot diff <from> <to>` - Compare two snapshots
560754

561755
### Options
562756

@@ -567,6 +761,17 @@ lrm cloud pull --no-backup
567761
- `--strategy <strategy>` - Resolution strategy (pull only)
568762
- `--config-only` - Sync configuration only
569763
- `--resources-only` - Sync resources only
764+
- `-m, --message <MESSAGE>` - Commit message (push only)
765+
766+
**Log Options:**
767+
- `-n, --number <COUNT>` - Number of entries to show (default: 10)
768+
- `--page <PAGE>` - Page number for pagination
769+
- `--oneline` - Compact one-line format
770+
771+
**Revert Options:**
772+
- `-m, --message <MESSAGE>` - Message describing the revert
773+
- `-y, --yes` - Skip confirmation prompt
774+
- `--dry-run` - Preview without reverting
570775

571776
**set-api-key Options:**
572777
- `[key]` - API key to store (will prompt if not provided)

0 commit comments

Comments
 (0)