From d7839ac607acae6673d244e89168ed086f31e238 Mon Sep 17 00:00:00 2001 From: Keepers Date: Thu, 4 May 2023 14:03:28 -0600 Subject: [PATCH] update cli docs (#3310) updates and improves cli docs. in part for easier reading and explanation. in part to remove all references to resource owner flags in details and restore. --- #### Does this PR need a docs update or release note? - [x] :white_check_mark: Yes, it's included #### Type of change - [x] :bug: Bugfix #### Test Plan - [x] :muscle: Manual --- CHANGELOG.md | 1 + src/cli/backup/exchange.go | 10 +++++----- src/cli/backup/onedrive.go | 12 ++++++------ src/cli/backup/sharepoint.go | 18 +++++++++++------- src/cli/restore/exchange.go | 13 +++++++------ src/cli/restore/onedrive.go | 12 ++++++------ src/cli/restore/sharepoint.go | 10 +++++----- 7 files changed, 41 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b7365277..5e1b36209 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Graph requests now automatically retry in case of a Bad Gateway or Gateway Timeout. - POST Retries following certain status codes (500, 502, 504) will re-use the post body instead of retrying with a no-content request. - Fix nil pointer exception when running an incremental backup on SharePoint where the base backup used an older index data format. +- --user and --mailbox flags (already not supported) have been removed from CLI examples for details and restore commands. ## [v0.7.0] (beta) - 2023-05-02 diff --git a/src/cli/backup/exchange.go b/src/cli/backup/exchange.go index aaaa41129..fd0a56bec 100644 --- a/src/cli/backup/exchange.go +++ b/src/cli/backup/exchange.go @@ -49,18 +49,18 @@ corso backup create exchange --mailbox '*'` exchangeServiceCommandDeleteExamples = `# Delete Exchange backup with ID 1234abcd-12ab-cd34-56de-1234abcd corso backup delete exchange --backup 1234abcd-12ab-cd34-56de-1234abcd` - exchangeServiceCommandDetailsExamples = `# Explore items in backup 1234abcd-12ab-cd34-56de-1234abcd (Alice's backup) -corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --mailbox alice@example.com + exchangeServiceCommandDetailsExamples = `# Explore items in Alice's latest backup (1234abcd...) +corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd -# Explore Alice's emails with subject containing "Hello world" in folder "Inbox" from a specific backup +# Explore emails in the folder "Inbox" with subject containing "Hello world" corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ --email-subject "Hello world" --email-folder Inbox -# Explore Bobs's events occurring after start of 2022 from a specific backup +# Explore calendar events occurring after start of 2022 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ --event-starts-after 2022-01-01T00:00:00 -# Explore Alice's contacts with name containing Andy from a specific backup +# Explore contacts named Andy corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ --contact-name Andy` ) diff --git a/src/cli/backup/onedrive.go b/src/cli/backup/onedrive.go index ec5c192f8..dca460de0 100644 --- a/src/cli/backup/onedrive.go +++ b/src/cli/backup/onedrive.go @@ -43,16 +43,16 @@ corso backup create onedrive --user '*'` oneDriveServiceCommandDeleteExamples = `# Delete OneDrive backup with ID 1234abcd-12ab-cd34-56de-1234abcd corso backup delete onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd` - oneDriveServiceCommandDetailsExamples = `# Explore Alice's files from backup 1234abcd-12ab-cd34-56de-1234abcd -corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --user alice@example.com + oneDriveServiceCommandDetailsExamples = `# Explore items in Bob's latest backup (1234abcd...) +corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd -# Explore Alice or Bob's files with name containing "Fiscal 22" in folder "Reports" +# Explore files in the folder "Reports" named "Fiscal 22" corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com,bob@example.com --file-name "Fiscal 22" --folder "Reports" + --file-name "Fiscal 22" --folder "Reports" -# Explore Alice's files created before end of 2015 from a specific backup +# Explore files created before the end of 2015 corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --file-created-before 2015-01-01T00:00:00` + --file-created-before 2015-01-01T00:00:00` ) // called by backup.go to map subcommands to provider-specific handling. diff --git a/src/cli/backup/sharepoint.go b/src/cli/backup/sharepoint.go index 354e4cf9e..7f48d4c33 100644 --- a/src/cli/backup/sharepoint.go +++ b/src/cli/backup/sharepoint.go @@ -40,10 +40,10 @@ const ( ) const ( - sharePointServiceCommandCreateExamples = `# Backup SharePoint data for a Site -corso backup create sharepoint --site + sharePointServiceCommandCreateExamples = `# Backup SharePoint data in the HR Site +corso backup create sharepoint --site https://example.com/hr -# Backup SharePoint for two sites: HR and Team +# Backup SharePoint for the HR and Team sites corso backup create sharepoint --site https://example.com/hr,https://example.com/team # Backup all SharePoint data for all Sites @@ -52,16 +52,20 @@ corso backup create sharepoint --site '*'` sharePointServiceCommandDeleteExamples = `# Delete SharePoint backup with ID 1234abcd-12ab-cd34-56de-1234abcd corso backup delete sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd` - sharePointServiceCommandDetailsExamples = `# Explore a site's files from backup 1234abcd-12ab-cd34-56de-1234abcd + sharePointServiceCommandDetailsExamples = `# Explore items in the HR site's latest backup (1234abcd...) corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd -# Find all files that were created before a certain date. +# Explore files in the folder "Reports" named "Fiscal 22" +corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \ + --file-name "Fiscal 22" --folder "Reports" + +# Explore files in the folder ""Display Templates/Style Sheets"" created before the end of 2015. corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \ --file-created-before 2015-01-01T00:00:00 --folder "Display Templates/Style Sheets" -# Find all files within a specific library. +# Explore all files within the document library "Work Documents" corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --library documents --folder "Display Templates/Style Sheets" + --library "Work Documents" ` ) diff --git a/src/cli/restore/exchange.go b/src/cli/restore/exchange.go index 99300a00b..f7f7fdd9c 100644 --- a/src/cli/restore/exchange.go +++ b/src/cli/restore/exchange.go @@ -44,18 +44,19 @@ const ( exchangeServiceCommand = "exchange" exchangeServiceCommandUseSuffix = "--backup " - exchangeServiceCommandRestoreExamples = `# Restore emails with ID 98765abcdef and 12345abcdef from a specific backup + //nolint:lll + exchangeServiceCommandRestoreExamples = `# Restore emails with ID 98765abcdef and 12345abcdef from Alice's last backup (1234abcd...) corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --email 98765abcdef,12345abcdef -# Restore Alice's emails with subject containing "Hello world" in "Inbox" from a specific backup +# Restore emails with subject containing "Hello world" in the "Inbox" corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --email-subject "Hello world" --email-folder Inbox + --email-subject "Hello world" --email-folder Inbox -# Restore Bobs's entire calendar from a specific backup +# Restore an entire calendar corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user bob@example.com --event-calendar Calendar + --event-calendar Calendar -# Restore contact with ID abdef0101 from a specific backup +# Restore the contact with ID abdef0101 corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --contact abdef0101` ) diff --git a/src/cli/restore/onedrive.go b/src/cli/restore/onedrive.go index 879b7f2c4..66e1f697e 100644 --- a/src/cli/restore/onedrive.go +++ b/src/cli/restore/onedrive.go @@ -46,19 +46,19 @@ const ( oneDriveServiceCommand = "onedrive" oneDriveServiceCommandUseSuffix = "--backup " - oneDriveServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef + oneDriveServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef in Bob's last backup (1234abcd...) corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef -# Restore file with ID 98765abcdef along with its associated permissions +# Restore the file with ID 98765abcdef along with its associated permissions corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef --restore-permissions -# Restore Alice's file named "FY2021 Planning.xlsx in "Documents/Finance Reports" from a specific backup +# Restore files named "FY2021 Planning.xlsx in "Documents/Finance Reports" corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \ - --user alice@example.com --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports" + --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports" -# Restore all files from Bob's folder that were created before 2020 when captured in a specific backup +# Restore all files and folders in folder "Documents/Finance Reports" that were created before 2020 corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd - --user bob@example.com --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00` + --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00` ) // `corso restore onedrive [...]` diff --git a/src/cli/restore/sharepoint.go b/src/cli/restore/sharepoint.go index baa8cb8f2..c56218d78 100644 --- a/src/cli/restore/sharepoint.go +++ b/src/cli/restore/sharepoint.go @@ -44,20 +44,20 @@ const ( sharePointServiceCommandUseSuffix = "--backup " //nolint:lll - sharePointServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef + sharePointServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef in Bob's latest backup (1234abcd...) corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef -# Restore a file named "ServerRenderTemplate.xsl in "Display Templates/Style Sheets". +# Restore files named "ServerRenderTemplate.xsl in the folder "Display Templates/Style Sheets". corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \ --file "ServerRenderTemplate.xsl" --folder "Display Templates/Style Sheets" -# Restore all files that were created before 2020. +# Restore all files in the folder "Display Templates/Style Sheets" that were created before 2020. corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd --file-created-before 2020-01-01T00:00:00 --folder "Display Templates/Style Sheets" -# Restore all files in a certain library. +# Restore all files in the "Documents" library. corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd - --library documents --folder "Display Templates/Style Sheets" ` + --library Documents --folder "Display Templates/Style Sheets" ` ) // `corso restore sharepoint [...]`