README.md in imap-backup-6.3.0 vs README.md in imap-backup-7.0.0.rc1
- old
+ new
@@ -3,220 +3,110 @@
# imap-backup
-*Backup GMail (or other IMAP) accounts to disk*
+Backup, restore and migrate email accounts.
+The backups can then be restored, used to migrate to another service,
+inspected or exported.
+
* [Source Code]
- * [API documentation]
+ * [Documentation]
* [Rubygem]
* [CI Status]
[Source Code]: https://github.com/joeyates/imap-backup "Source code at GitHub"
-[API documentation]: https://rubydoc.info/gems/imap-backup/frames "RDoc API Documentation at Rubydoc.info"
+[Documentation]: https://rubydoc.info/gems/imap-backup/frames "RDoc API Documentation at Rubydoc.info"
[Rubygem]: https://rubygems.org/gems/imap-backup "Ruby gem at rubygems.org"
[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
-# Installation
+# Backup Emails
-```shell
-$ gem install 'imap-backup'
-```
+imap-backup downloads emails and stores them on disk.
-# Commands
+The backup is incremental and interruptable, so backups won't get messed if your connection goes down during an operation.
-For a full list, run
+# Installation
+## Homebrew (macOS)
+
+If you have [Homebrew](https://brew.sh/), do this:
+
+```sh
+brew install imap-backup
```
-$ imap-backup help
-```
-For more information about a command, run
+## As a Ruby Gem
-```shell
-$ imap-backup help COMMAND
+```sh
+gem install imap-backup
```
+If that doesn't work, see the [detailed installation instructions](docs/installation/rubygem.md).
+
+## From Source Code
+
+If you want to use imap-backup directly from the source code, see [here](docs/installation/source.md).
+
# Setup
-In order to do backups, you need to add accounts via a menu-driven command
+As a first step, you need to add accounts via a menu-driven command
line program:
Run:
-```shell
-$ imap-backup setup
+```sh
+imap-backup setup
```
## GMail
To use imap-backup with GMail, you will need to enable 'App passwords' on your account.
-## Folders
+# Run Backup
-By default, all folders are backed-up. You can override this by choosing
-specific folders.
+Manually, from the command line:
-## Configuration file
-
-`setup` creates the file `~/.imap-backup/config.json`
-
-E.g.:
-
-```json
-{
- "accounts": [
- {
- "username": "my.user@gmail.com",
- "password": "secret",
- "local_path": "/path/to/backup/root",
- "folders":
- [
- {"name": "[Gmail]/All Mail"},
- {"name": "my_folder"}
- ]
- }
- ]
-}
+```sh
+imap-backup
```
-It connects to GMail by default, but you can also specify a server:
+Alternatively, add it to your crontab.
-```json
-{
- "accounts": [
- {
- "username": "my.user@gmail.com",
- "password": "secret",
- "server": "my.imap.example.com",
- "local_path": "/path/to/backup/root",
- "folders":
- [
- {"name": "[Gmail]/All Mail"},
- {"name": "my_folder"}
- ]
- }
- ]
-}
-```
+Emails are stored on disk in [Mbox files](./docs/files/mboxrd.md) for each folder, with metadata
+stored in [Imap files](./docs/files/imap.md).
-## Connection options
+# Commands
-You can override the parameters passed to `Net::IMAP` with `connection_options`.
+* [folders](./commands/folders.md)
+* [restore](./commands/restore.md)
+* [status](./commands/status.md)
-Specifically, if you are using a self-signed certificate and get SSL errors, e.g.
-`certificate verify failed`, you can choose to not verify the TLS connection:
+For a full list of available commands, run
-```json
-{
- "accounts": [
- {
- "username": "my.user@gmail.com",
- "password": "secret",
- "server": "my.imap.example.com",
- "local_path": "/path/to/backup/root",
- "folders": [
- {"name": "[Gmail]/All Mail"},
- {"name": "my_folder"}
- ],
- "connection_options": {
- "ssl": {"verify_mode": 0},
- "port": 993
- }
- }
- ]
-}
+```sh
+imap-backup help
```
-# Security
+For more information about a command, run
-Note that email usernames and passwords are held in plain text
-in the configuration file.
-
-The directory ~/.imap-backup, the configuration file and all backup
-directories have their access permissions set to only allow access
-by your user. This is not done on Windows - see below.
-
-## Windows
-
-Due to the complexity of managing permissions on Windows,
-directory and file access permissions are not set explicity.
-
-A pull request that implements permissions management on Windows
-would be welcome!
-
-# Run Backup
-
-Manually, from the command line:
-
-```shell
-$ imap-backup
+```sh
+imap-backup help COMMAND
```
-Alternatively, add it to your crontab.
+## Configuration
-# Result
+`imap-backup setup` creates the file `~/.imap-backup/config.json`.
-Each folder is saved to an mbox file.
-Alongside each mbox is a file with extension '.imap', which lists the source IMAP
-UIDs to allow a full restore.
+[More information about configuration is available in the specific documentation](./docs/configuration.md).
-# Local commands
-
-There a various commands for viewing local backup status.
-
-To view the list, use
-
-```shell
-$ imap_backup help local
-```
-
# Troubleshooting
If you have problems:
1. ensure that you have the latest release,
-2. turn on debugging output:
+2. turn on debugging output via the `imap-backup setup` main menu.
-```json
-{
- "accounts":
- [
- ...
- ],
- "debug": true
-}
-```
+# Development
-# Restore
-
-All missing messages are pushed to the IMAP server.
-Existing messages are left unchanged.
-
-This functionality requires that the IMAP server supports the UIDPLUS
-extension to IMAP4.
-
-# Other Usage
-
-List IMAP folders:
-
-```shell
-$ imap-backup folders
-```
-
-Get statistics of emails to download per folder:
-
-```shell
-$ imap-backup status
-```
-
-# Design Goals
-
-* Secure - use a local file protected by permissions
-* Restartable - calculate start point based on already downloaded messages
-* Standalone - do not rely on an email client or MTA
-
-# Documentation
-
-* [Development](./docs/development.md)
-* [Restore](./docs/restore.md)
+See the [Development documentation](./docs/development.md)