README.md in imap-backup-14.4.4 vs README.md in imap-backup-14.4.5
- old
+ new
@@ -1,201 +1,131 @@
+# imap-backup API Documentation
+
[][CI Status]
[][GitHub Stars]
+
-# imap-backup
+[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
+[GitHub Stars]: https://github.com/joeyates/imap-backup/stargazers "GitHub Stars"
-Backup, restore and migrate email accounts.
+This is the developer documentation for imap-backup's **code**.
-# Quick Start
+Usage documentation is on [GitHub](https://github.com/joeyates/imap-backup).
-```sh
-brew install imap-backup # for macOS
-gem install imap-backup --no-document # for Linux
-imap-backup setup
-imap-backup
-```
+You can get an overview of the program's structure from the
+{file:ARCHITECTURE.md ARCHITECTURE} file.
-# Modes
+The {file:CHANGELOG.md CHANGELOG} has a history of the changes to the program.
-There are two types of backups:
+# Design Goals
-* Keep all (the default) - progressively saves a local copy of all emails,
-* Mirror - adds and deletes emails from the local copy to keep it up to date with the account.
+* Secure - use a local configuration file protected by permissions
+* Restartable - calculate start point based on already downloaded messages
+* Standalone - do not rely on an email client or MTA
-# What You Can Do with a Backup
+# Repository
-* Migrate - use the local copy to populate emails on another account. This is a once-only action that deletes any existing emails on the destination account.
-* Mirror - make a destination account match the local copy. This action can be repeated.
-* Restore - push the local copy back to the original account.
+After cloning the repo, run the following command to get
+better `git blame` output:
-See below for a [full list of commands](#commands).
-
-# Installation
-
-## Docker or Podman
-
-If you have Docker or Podman installed, the easist way to use imap-backup
-is via the container image.
-
-You'll need to choose a path on your computer where your backups will be saved,
-we'll use `./my-data` here.
-
-If you have just one account, you can do as follows
-
```sh
-docker run -v ./my-data:/data -ti ghcr.io/joeyates/imap-backup:latest \
- imap-backup single backup \
- --email me@example.com --password mysecret --server imap.example.com \
- --path /data/me_example.com
+git config --local blame.ignoreRevsFile .git-blame-ignore-revs
```
-Podman will work exactly the same.
+# Testing
-If you have multiple accounts, you can create a configuration file.
+## Feature Specs
-You'll need to choose a path on your computer where your configuration will be saved,
-we'll use `./my-config` here.
+Specs under `specs/features` are integration specs.
+Some of these specs run against two local IMAP servers
+controlled by Podman (or Docker) Compose.
-First, run the menu-driven setup program to configure your accounts
+Start them before running the test suite
```sh
-docker run -ti -v ./my-config:/config -v ./my-data:/data -ti ghcr.io/joeyates/imap-backup:latest \
- imap-backup setup -c /config/imap-backup.json
+$ podman-compose -f dev/compose.yml up -d
```
-Then, run the backup
+or, with Docker
```sh
-docker run -v ./my-config:/config -v ./my-data:/data -ti ghcr.io/joeyates/imap-backup:latest \
- imap-backup backup -c /config/imap-backup.json
+$ docker-compose -f dev/compose.yml up -d
```
+Then, run all specs
-## Homebrew (macOS)
-
-
-
-If you have [Homebrew](https://brew.sh/), do this:
-
```sh
-brew install imap-backup
+$ rspec
```
-## As a Ruby Gem
+To exclude container-based tests
```sh
-gem install imap-backup --no-document
+$ rspec --tag ~docker
```
-If that doesn't work, see the [detailed installation instructions](docs/installation/rubygem.md).
+To run **just** the feature specs
-## From Source Code
-
-If you want to use imap-backup directly from the source code, see [here](docs/installation/source.md).
-
-# Setup
-
-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
+rspec spec/features/**/*_spec.rb
```
-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).
+## Full Test Run
-## GMail
+The full test run includes RSpec specs **and** Rubocop checks
-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).
-See [this blog post about using imap-backup with email-oauth2-proxy](https://joeyates.info/posts/back-up-gmail-accounts-with-imap-backup-using-email-oauth2-proxy/).
-
-# Backup
-
-Manually, from the command line:
-
```sh
-imap-backup
+rake
```
-Alternatively, add it to your crontab.
+# Test Debugging
-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).
+The feature specs are run 'out of process' via the Aruba gem.
+In order to see debugging output from the process,
+use `last_command_started.output`.
-# Commands
+# Older Rubies
-* [`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)
+A Containerfile is available to allow testing with all available Ruby versions,
+see the README in the `dev` directory.
-For a full list of available commands, run
+# Performance Specs
```sh
-imap-backup help
+PERFORMANCE=1 rspec --order=defined
```
-For more information about a command, run
+Beware: the performance spec (just backup for now) takes a very
+long time to run, approximately 24 hours!
-```sh
-imap-backup help COMMAND
-```
+# Access Docker imap server
-# Performance
+```ruby
+require "net/imap"
+require_relative "spec/features/support/30_email_server_helpers"
-There are a couple of performance tweaks that you can use
-to improve backup speed.
+include EmailServerHelpers
-These are activated via two settings:
+test_connection = test_server_connection_parameters
-* Global setting "Delay download writes",
-* Account setting "Multi-fetch size".
+test_imap = Net::IMAP.new(test_connection[:server], test_connection[:connection_options])
+test_imap.login(test_connection[:username], test_connection[:password])
-See [the performance document](docs/performance.md) for more information.
+message = "From: #{test_connection[:username]}\nSubject: Some Subject\n\nHello!\n"
+response = test_imap.append("INBOX", message, nil, nil)
-# Troubleshooting
+test_imap.examine("INBOX")
+uids = test_imap.uid_search(["ALL"]).sort
-If you have problems:
+fetch_data_items = test_imap.uid_fetch(uids, ["BODY[]"])
+```
-1. ensure that you have the latest release,
-2. run `imap-backup` with the `-v` or `--verbose` parameter.
+# Contributing
-# Development
-
-
-
-See the [Development documentation](./docs/development.md) for notes
-on development and testing.
-
-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
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request