From 5bd8a6d7eba9b0482f26ad06c5458c6664de251a Mon Sep 17 00:00:00 2001 From: Konrad Wojas Date: Mon, 11 Jan 2021 11:50:02 +0800 Subject: [PATCH 1/2] Extend help output with short overview The list of subcommands can be confusing for first time users. This adds a short overview of the most important commands to help get people started. --- changelog/unreleased/pull-3225 | 6 ++++++ cmd/restic/main.go | 38 ++++++++++++++++++++++++++++------ 2 files changed, 38 insertions(+), 6 deletions(-) create mode 100644 changelog/unreleased/pull-3225 diff --git a/changelog/unreleased/pull-3225 b/changelog/unreleased/pull-3225 new file mode 100644 index 000000000..4d2fb73e2 --- /dev/null +++ b/changelog/unreleased/pull-3225 @@ -0,0 +1,6 @@ +Enhancement: Extend cli help output + +Added a short overview of the most important commands to the commandline +help output to help new users get started. + +https://github.com/restic/restic/pull/3225 diff --git a/cmd/restic/main.go b/cmd/restic/main.go index 64b75b43a..267dc44c2 100644 --- a/cmd/restic/main.go +++ b/cmd/restic/main.go @@ -18,14 +18,40 @@ import ( "github.com/restic/restic/internal/errors" ) -// cmdRoot is the base command when no other command has been specified. -var cmdRoot = &cobra.Command{ - Use: "restic", - Short: "Backup and restore files", - Long: ` +// LongDescription is shown in the cli help output +const LongDescription = ` restic is a backup program which allows saving multiple revisions of files and directories in an encrypted repository stored on different backends. -`, + +To get started with a local test repository, first define some environment variables: + export RESTIC_REPOSITORY=/tmp/restic-example + export RESTIC_PASSWORD=some-strong-password + +Initialize the repository (first time only): + restic init + +Create your first backup: + restic backup /etc/hosts + +You can list all the snapshots you created with: + restic snapshots + +You can restore a backup by noting the snapshot ID you want and running: + restic restore --target /tmp/some-target-dir your-snapshot-ID + +It is a good idea to periodically check your repository's metadata: + restic check + # or full data: + restic check --read-data + +The full documentation can be found at https://restic.readthedocs.io/ +` + +// cmdRoot is the base command when no other command has been specified. +var cmdRoot = &cobra.Command{ + Use: "restic", + Short: "Backup and restore files", + Long: LongDescription, SilenceErrors: true, SilenceUsage: true, DisableAutoGenTag: true, From ae13cf15c1999d4cde3697a3b4395716a359a5ab Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sun, 23 Jul 2023 12:09:01 +0200 Subject: [PATCH 2/2] doc: move quickstart to docs --- changelog/unreleased/pull-3225 | 6 ----- cmd/restic/main.go | 38 ++++++----------------------- doc/010_introduction.rst | 44 ++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 37 deletions(-) delete mode 100644 changelog/unreleased/pull-3225 diff --git a/changelog/unreleased/pull-3225 b/changelog/unreleased/pull-3225 deleted file mode 100644 index 4d2fb73e2..000000000 --- a/changelog/unreleased/pull-3225 +++ /dev/null @@ -1,6 +0,0 @@ -Enhancement: Extend cli help output - -Added a short overview of the most important commands to the commandline -help output to help new users get started. - -https://github.com/restic/restic/pull/3225 diff --git a/cmd/restic/main.go b/cmd/restic/main.go index 267dc44c2..17b9c468d 100644 --- a/cmd/restic/main.go +++ b/cmd/restic/main.go @@ -18,40 +18,16 @@ import ( "github.com/restic/restic/internal/errors" ) -// LongDescription is shown in the cli help output -const LongDescription = ` +// cmdRoot is the base command when no other command has been specified. +var cmdRoot = &cobra.Command{ + Use: "restic", + Short: "Backup and restore files", + Long: ` restic is a backup program which allows saving multiple revisions of files and directories in an encrypted repository stored on different backends. -To get started with a local test repository, first define some environment variables: - export RESTIC_REPOSITORY=/tmp/restic-example - export RESTIC_PASSWORD=some-strong-password - -Initialize the repository (first time only): - restic init - -Create your first backup: - restic backup /etc/hosts - -You can list all the snapshots you created with: - restic snapshots - -You can restore a backup by noting the snapshot ID you want and running: - restic restore --target /tmp/some-target-dir your-snapshot-ID - -It is a good idea to periodically check your repository's metadata: - restic check - # or full data: - restic check --read-data - -The full documentation can be found at https://restic.readthedocs.io/ -` - -// cmdRoot is the base command when no other command has been specified. -var cmdRoot = &cobra.Command{ - Use: "restic", - Short: "Backup and restore files", - Long: LongDescription, +The full documentation can be found at https://restic.readthedocs.io/ . +`, SilenceErrors: true, SilenceUsage: true, DisableAutoGenTag: true, diff --git a/doc/010_introduction.rst b/doc/010_introduction.rst index 5c213f6cd..e6bffdea1 100644 --- a/doc/010_introduction.rst +++ b/doc/010_introduction.rst @@ -17,3 +17,47 @@ Introduction Restic is a fast and secure backup program. In the following sections, we will present typical workflows, starting with installing, preparing a new repository, and making the first backup. + +Quickstart Guide +**************** + +To get started with a local repository, first define some environment variables: + +.. code-block:: console + + export RESTIC_REPOSITORY=/srv/restic-repo + export RESTIC_PASSWORD=some-strong-password + +Initialize the repository (first time only): + +.. code-block:: console + + restic init + +Create your first backup: + +.. code-block:: console + + restic backup ~/work + +You can list all the snapshots you created with: + +.. code-block:: console + + restic snapshots + +You can restore a backup by noting the snapshot ID you want and running: + +.. code-block:: console + + restic restore --target /tmp/restore-work your-snapshot-ID + +It is a good idea to periodically check your repository's metadata: + +.. code-block:: console + + restic check + # or full data: + restic check --read-data + +For more details continue reading the next sections.