1  # KeepSync CLI Versioning Commands
  2  
  3  This document describes the versioning commands available in the KeepSync CLI. These commands allow you to manage file versions, including listing, retrieving, restoring, and deleting versions, as well as managing version tags and metadata.
  4  
  5  ## Basic Version Commands
  6  
  7  ### List Versions
  8  
  9  List all versions of a file:
 10  
 11  ```bash
 12  keepsync version list /path/to/file
 13  ```
 14  
 15  This command displays a table with the following information for each version:
 16  - Version ID
 17  - Size
 18  - Creation time
 19  - Whether it's the latest version
 20  - Whether it's a differential version
 21  - Compression status
 22  - Binary diff status
 23  - Tags
 24  
 25  ### Get a Specific Version
 26  
 27  Retrieve a specific version of a file:
 28  
 29  ```bash
 30  keepsync version get /path/to/file version_id /path/to/output
 31  ```
 32  
 33  This command retrieves the specified version of the file and saves it to the output path.
 34  
 35  ### Restore a Version
 36  
 37  Restore a file to a specific version:
 38  
 39  ```bash
 40  keepsync version restore /path/to/file version_id
 41  ```
 42  
 43  This command restores the file to the specified version.
 44  
 45  ### Delete a Version
 46  
 47  Delete a specific version of a file:
 48  
 49  ```bash
 50  keepsync version delete /path/to/file version_id
 51  ```
 52  
 53  This command deletes the specified version of the file.
 54  
 55  ### Purge Old Versions
 56  
 57  Delete all versions of a file except the latest N versions:
 58  
 59  ```bash
 60  keepsync version purge /path/to/file keep_latest
 61  ```
 62  
 63  This command deletes all versions of the file except the latest `keep_latest` versions.
 64  
 65  ### Show Differences Between Versions
 66  
 67  Show the differences between two versions of a file:
 68  
 69  ```bash
 70  keepsync version diff /path/to/file version_id1 version_id2
 71  ```
 72  
 73  This command shows the differences between the two specified versions of the file. For text files, it shows a line-by-line diff. For binary files, it shows a size comparison.
 74  
 75  ## Tag Management Commands
 76  
 77  ### Add a Tag to a Version
 78  
 79  Add a tag to a specific version of a file:
 80  
 81  ```bash
 82  keepsync version tag add /path/to/file version_id tag_name
 83  ```
 84  
 85  This command adds the specified tag to the specified version of the file.
 86  
 87  ### Remove a Tag from a Version
 88  
 89  Remove a tag from a specific version of a file:
 90  
 91  ```bash
 92  keepsync version tag remove /path/to/file version_id tag_name
 93  ```
 94  
 95  This command removes the specified tag from the specified version of the file.
 96  
 97  ### List All Tags
 98  
 99  List all available tags:
100  
101  ```bash
102  keepsync version tag list
103  ```
104  
105  This command displays a table with the following information for each tag:
106  - Name
107  - Color
108  - Description
109  - Creation time
110  
111  ### Create a New Tag
112  
113  Create a new tag:
114  
115  ```bash
116  keepsync version tag create tag_name color description
117  ```
118  
119  This command creates a new tag with the specified name, color, and description.
120  
121  ### Delete a Tag
122  
123  Delete a tag:
124  
125  ```bash
126  keepsync version tag delete tag_name
127  ```
128  
129  This command deletes the specified tag.
130  
131  ## Search Commands
132  
133  ### Search for Versions by Tag
134  
135  Search for versions of a file with a specific tag:
136  
137  ```bash
138  keepsync version search by-tag /path/to/file tag_name
139  ```
140  
141  This command displays a table with all versions of the file that have the specified tag.
142  
143  ## Metadata Commands
144  
145  ### Add a Comment to a Version
146  
147  Add a comment to a specific version of a file:
148  
149  ```bash
150  keepsync version comment /path/to/file version_id "Your comment here"
151  ```
152  
153  This command adds the specified comment to the specified version of the file.
154  
155  ### Set the Author of a Version
156  
157  Set the author of a specific version of a file:
158  
159  ```bash
160  keepsync version author /path/to/file version_id "Author Name"
161  ```
162  
163  This command sets the author of the specified version of the file.
164  
165  ## Examples
166  
167  ### Basic Version Management
168  
169  ```bash
170  # List all versions of a file
171  keepsync version list /data/important.txt
172  
173  # Get a specific version
174  keepsync version get /data/important.txt v1 /tmp/important-v1.txt
175  
176  # Restore to a previous version
177  keepsync version restore /data/important.txt v1
178  
179  # Delete an old version
180  keepsync version delete /data/important.txt v2
181  
182  # Keep only the 5 latest versions
183  keepsync version purge /data/important.txt 5
184  
185  # Compare two versions
186  keepsync version diff /data/important.txt v1 v3
187  ```
188  
189  ### Tag Management
190  
191  ```bash
192  # Create tags for different states
193  keepsync version tag create stable "#00FF00" "Stable version"
194  keepsync version tag create beta "#FFFF00" "Beta version"
195  keepsync version tag create alpha "#FF0000" "Alpha version"
196  
197  # List all available tags
198  keepsync version tag list
199  
200  # Tag a version
201  keepsync version tag add /data/important.txt v1 stable
202  
203  # Remove a tag
204  keepsync version tag remove /data/important.txt v2 beta
205  
206  # Find all stable versions
207  keepsync version search by-tag /data/important.txt stable
208  ```
209  
210  ### Metadata Management
211  
212  ```bash
213  # Add a comment to a version
214  keepsync version comment /data/important.txt v1 "Fixed critical bug"
215  
216  # Set the author of a version
217  keepsync version author /data/important.txt v1 "John Doe"
218  ```
219  
220  ## Integration with Other Features
221  
222  The versioning commands integrate with other KeepSync features:
223  
224  - **Differential Versioning**: Versions created with differential versioning are marked as such in the version list.
225  - **Compression**: Versions with compression are marked as such in the version list.
226  - **Binary Diff**: Versions with binary diff are marked as such in the version list.
227  - **Metadata**: Version metadata like comments and authors can be managed through the CLI.
228  - **Tags**: Version tags can be managed through the CLI.
229  
230  ## Configuration
231  
232  Versioning behavior can be configured in the KeepSync configuration file:
233  
234  ```json
235  {
236    "versioning": {
237      "enabled": true,
238      "auto_version": true,
239      "max_versions": 10,
240      "diff_versioning_enabled": true,
241      "diff_threshold": 1024,
242      "full_version_interval": 5,
243      "compression_enabled": true,
244      "binary_diff_enabled": true
245    }
246  }
247  ```
248  
249  These settings control the default behavior of the versioning system, including whether to use differential versioning, compression, and binary diff.