README.md in imap-backup-13.4.0 vs README.md in imap-backup-14.0.0
- old
+ new
@@ -1,19 +1,20 @@
[][CI Status]
+[][GitHub Stars]
# imap-backup
Backup, restore and migrate email accounts.
# Quick Start
```sh
brew install imap-backup # for macOS
-gem install imap-backup # for Linux
+gem install imap-backup --no-document # for Linux
imap-backup setup
imap-backup
```
# Modes
@@ -33,39 +34,47 @@
# Installation
## Homebrew (macOS)
+
+
If you have [Homebrew](https://brew.sh/), do this:
```sh
brew install imap-backup
```
## As a Ruby Gem
```sh
-gem install imap-backup
+gem install imap-backup --no-document
```
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
-As a first step, you need to add accounts via a menu-driven command
-line program:
+Normally you will want to backup a number of email accounts.
+Doing so requires the creation of a config file.
+You do this via a menu-driven command line program:
+
Run:
```sh
imap-backup setup
```
+As an alternative, if you only want to backup a single account,
+you can pass all the necessary parameters directly to the `single backup` command
+(see the [`single backup`](docs/commands/single-backup.md) docs).
+
## GMail
To use imap-backup with GMail, Office 365 and other services that require
OAuth2 authentication, you can use [email-oauth2-proxy](https://github.com/simonrob/email-oauth2-proxy)
to handle authentication, and then connect to the proxy on a local port.
@@ -78,28 +87,29 @@
imap-backup
```
Alternatively, add it to your crontab.
-Backups can also be inspected, for example via [local show](docs/commands/local-show.md)
-and exported via [utils export-to-thunderbird](docs/commands/utils-export-to-thunderbird.md).
+Backups can also be inspected, for example via [`local show`](docs/commands/local-show.md)
+and exported via [`utils export-to-thunderbird`](docs/commands/utils-export-to-thunderbird.md).
# Commands
-* [backup](docs/commands/backup.md)
-* [local accounts](docs/commands/local-accounts.md)
-* [local check](docs/commands/local-check.md)
-* [local folders](docs/commands/local-folders.md)
-* [local list](docs/commands/local-list.md)
-* [local show](docs/commands/local-show.md)
-* [migrate](docs/commands/migrate.md)
-* [mirror](docs/commands/mirror.md)
-* [remote folders](docs/commands/remote-folders.md)
-* [restore](docs/commands/restore.md)
-* [setup](docs/commands/setup.md)
-* [utils export-to-thunderbird](docs/commands/utils-export-to-thunderbird.md)
-* [utils ignore-history](docs/commands/utils-ignore-history.md)
+* [`backup`](docs/commands/backup.md)
+* [`local accounts`](docs/commands/local-accounts.md)
+* [`local check`](docs/commands/local-check.md)
+* [`local folders`](docs/commands/local-folders.md)
+* [`local list`](docs/commands/local-list.md)
+* [`local show`](docs/commands/local-show.md)
+* [`migrate`](docs/commands/migrate.md)
+* [`mirror`](docs/commands/mirror.md)
+* [`remote folders`](docs/commands/remote-folders.md)
+* [`restore`](docs/commands/restore.md)
+* [`setup`](docs/commands/setup.md)
+* [`single backup`](docs/commands/single-backup.md)
+* [`utils export-to-thunderbird`](docs/commands/utils-export-to-thunderbird.md)
+* [`utils ignore-history`](docs/commands/utils-ignore-history.md)
For a full list of available commands, run
```sh
imap-backup help
@@ -116,70 +126,37 @@
There are a couple of performance tweaks that you can use
to improve backup speed.
These are activated via two settings:
-* Global setting "Delay download writes"
-* Account setting "Multi-fetch size"
+* Global setting "Delay download writes",
+* Account setting "Multi-fetch size".
-As with all performance tweaks, there are trade-offs.
-If you are using a small virtual server or Raspberry Pi
-to run your backups, you will probably want to leave
-the default settings.
-If, on the other hand, you are using a computer with a
-fair bit of RAM, and you are dealing with a *lot* of email,
-then changing these settings may be worthwhile.
+See [the performance document](docs/performance.md) for more information.
-## Delay download writes
-
-This setting affects all account backups.
-
-By default, `imap-backup` uses the "delay metadata" strategy.
-As messages are being backed-up, the message *text*
-is written to disk, while the related metadata is stored in memory.
-
-While this uses a little more memory, it avoids rewiting a growing JSON
-file for every message, speeding things up and reducing disk wear.
-
-The alternative strategy, called "direct", writes everything to disk
-as it is received. This method is slower, but has the advantage
-of using slightly less memory, which may be important on very
-resource-limited systems, like Raspberry Pis.
-
-## Multi-fetch Size
-
-By default, during backup, each message is downloaded one-by-one.
-
-Using this setting, you can download chunks of emails at a time,
-potentially speeding up the process.
-
-Using multi-fetch *will* mean that the backup process will use
-more memory - equivalent to the size of the groups of messages
-that are downloaded.
-
-This behaviour may also exceed the rate limits on your email provider,
-so it's best to check before cranking it up!
-
# Troubleshooting
If you have problems:
1. ensure that you have the latest release,
2. run `imap-backup` with the `-v` or `--verbose` parameter.
# Development
+
+
See the [Development documentation](./docs/development.md) for notes
on development and testing.
-See [the CHANGELOG](./CHANGELOG.md) to a list of changes that have been
+See [the CHANGELOG](./CHANGELOG.md) for a list of changes that have been
made in each release.
* [Source Code]
* [Code Documentation]
* [Rubygem]
* [CI Status]
[Source Code]: https://github.com/joeyates/imap-backup "Source code at GitHub"
+[GitHub Stars]: https://github.com/joeyates/imap-backup/stargazers "GitHub Stars"
[Code Documentation]: https://rubydoc.info/gems/imap-backup/frames "Code 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