Skip to content
This repository has been archived by the owner on Oct 11, 2024. It is now read-only.

Commit

Permalink
Add Examples section to CLI usage and docs (#1050)
Browse files Browse the repository at this point in the history 
## Description

Adds Examples to CLI usage output and the auto-gen docs

Also cleans up:
* OneDrive flags and flags help
* Addition of OneDrive generated files to docs 


## Type of change

<!--- Please check the type of change your PR introduces: --->
- [x] 🌻 Feature
- [ ] 🐛 Bugfix
- [x] 🗺️ Documentation
- [ ] 🤖 Test
- [ ] 💻 CI/Deployment
- [ ] 🐹 Trivial/Minor

## Issue(s)

<!-- Can reference multiple issues. Use one of the following "magic words" - "closes, fixes" to auto-close the Github issue. -->
* Fixes #529  

## Test Plan

<!-- How will this be tested prior to merging.-->
- [x] 💪 Manual
- [ ] ⚡ Unit test
- [ ] 💚 E2E
  • Loading branch information
@gmatev
gmatev authored Oct 5, 2022
1 parent 3f0951d commit 3a1eb1e
Show file tree
Hide file tree
Showing 8 changed files with 190 additions and 65 deletions.
5 changes: 4 additions & 1 deletion docs/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,10 @@ const sidebars = {
items: [
'cli/corso_repo_init_s3', 'cli/corso_repo_connect_s3',
'cli/corso_backup_create_exchange', 'cli/corso_backup_list_exchange', 'cli/corso_backup_details_exchange',
'cli/corso_restore_exchange', 'cli/corso_env'
'cli/corso_restore_exchange',
'cli/corso_backup_create_onedrive', 'cli/corso_backup_list_onedrive', 'cli/corso_backup_details_onedrive',
'cli/corso_restore_onedrive',
'cli/corso_env'
]
},
{
Expand Down
50 changes: 41 additions & 9 deletions src/cli/backup/exchange.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,40 @@ const (

const (
exchangeServiceCommand = "exchange"
exchangeServiceCommandCreateUseSuffix = " --all | --user <userId or email>"
exchangeServiceCommandCreateUseSuffix = " --user <userId or email> | '" + utils.Wildcard + "'"
exchangeServiceCommandDeleteUseSuffix = " --backup <backupId>"
exchangeServiceCommandDetailsUseSuffix = " --backup <backupId>"
)

const (
exchangeServiceCommandCreateExamples = `# Backup all Exchange data for Alice
corso backup create exchange --user [email protected]
# Backup only Exchange contacts for Alice and Bob
corso backup create exchange --user [email protected],[email protected] --data contacts
# Backup all Exchange data for all M365 users
corso backup create exchange --user '*'`

exchangeServiceCommandDeleteExamples = `# Delete Exchange backup with ID 1234abcd-12ab-cd34-56de-1234abcd
corso backup delete exchange --backup 1234abcd-12ab-cd34-56de-1234abcd`

exchangeServiceCommandDetailsExamples = `# Explore Alice's items in backup 1234abcd-12ab-cd34-56de-1234abcd
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --user [email protected]
# Explore Alice's emails with subject containing "Hello world" in folder "Inbox" from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user [email protected] --email-subject "Hello world" --email-folder Inbox
# Explore Bobs's events occurring after start of 2022 from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user [email protected] --event-starts-after 2022-01-01T00:00:00
# Explore Alice's contacts with name containing Andy from a specific backup
corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user [email protected] --contact-name Andy`
)

// called by backup.go to map parent subcommands to provider-specific handling.
func addExchangeCommands(parent *cobra.Command) *cobra.Command {
var (
Expand All @@ -76,6 +105,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
c, fs = utils.AddCommand(parent, exchangeCreateCmd())

c.Use = c.Use + exchangeServiceCommandCreateUseSuffix
c.Example = utils.IndentExamples(exchangeServiceCommandCreateExamples)

// Flags addition ordering should follow the order we want them to appear in help and docs:
// More generic (ex: --all) and more frequently used flags take precedence.
Expand All @@ -85,7 +115,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
fs.StringSliceVar(
&user,
"user", nil,
"Backup Exchange data by user ID; accepts "+utils.Wildcard+" to select all users")
"Backup Exchange data by user ID; accepts '"+utils.Wildcard+"' to select all users")
fs.StringSliceVar(
&exchangeData,
"data", nil,
Expand All @@ -99,6 +129,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
c, fs = utils.AddCommand(parent, exchangeDetailsCmd())

c.Use = c.Use + exchangeServiceCommandDetailsUseSuffix
c.Example = utils.IndentExamples(exchangeServiceCommandDetailsExamples)

// Flags addition ordering should follow the order we want them to appear in help and docs:
// More generic (ex: --all) and more frequently used flags take precedence.
Expand All @@ -109,17 +140,17 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
fs.StringSliceVar(
&user,
"user", nil,
"Select backup details by user ID; accepts "+utils.Wildcard+" to select all users.")
"Select backup details by user ID; accepts '"+utils.Wildcard+"' to select all users.")

// email flags
fs.StringSliceVar(
&email,
"email", nil,
"Select backup details for emails by email ID; accepts "+utils.Wildcard+" to select all emails.")
"Select backup details for emails by email ID; accepts '"+utils.Wildcard+"' to select all emails.")
fs.StringSliceVar(
&emailFolder,
"email-folder", nil,
"Select backup details for emails within a folder; accepts "+utils.Wildcard+" to select all email folders.")
"Select backup details for emails within a folder; accepts '"+utils.Wildcard+"' to select all email folders.")
fs.StringVar(
&emailSubject,
"email-subject", "",
Expand All @@ -141,11 +172,11 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
fs.StringSliceVar(
&event,
"event", nil,
"Select backup details for events by event ID; accepts "+utils.Wildcard+" to select all events.")
"Select backup details for events by event ID; accepts '"+utils.Wildcard+"' to select all events.")
fs.StringSliceVar(
&eventCalendar,
"event-calendar", nil,
"Select backup details for events under a calendar; accepts "+utils.Wildcard+" to select all events.")
"Select backup details for events under a calendar; accepts '"+utils.Wildcard+"' to select all events.")
fs.StringVar(
&eventSubject,
"event-subject", "",
Expand All @@ -171,11 +202,11 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
fs.StringSliceVar(
&contact,
"contact", nil,
"Select backup details for contacts by contact ID; accepts "+utils.Wildcard+" to select all contacts.")
"Select backup details for contacts by contact ID; accepts '"+utils.Wildcard+"' to select all contacts.")
fs.StringSliceVar(
&contactFolder,
"contact-folder", nil,
"Select backup details for contacts within a folder; accepts "+utils.Wildcard+" to select all contact folders.")
"Select backup details for contacts within a folder; accepts '"+utils.Wildcard+"' to select all contact folders.")

fs.StringVar(
&contactName,
Expand All @@ -186,6 +217,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command {
c, fs = utils.AddCommand(parent, exchangeDeleteCmd())

c.Use = c.Use + exchangeServiceCommandDeleteUseSuffix
c.Example = utils.IndentExamples(exchangeServiceCommandDeleteExamples)

fs.StringVar(&backupID, "backup", "", "ID of the backup to delete. (required)")
cobra.CheckErr(c.MarkFlagRequired("backup"))
Expand Down
73 changes: 52 additions & 21 deletions src/cli/backup/onedrive.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,36 @@ import (

const (
oneDriveServiceCommand = "onedrive"
oneDriveServiceCommandCreateUseSuffix = " --user <userId or email> | " + utils.Wildcard
oneDriveServiceCommandCreateUseSuffix = " --user <userId or email> | '" + utils.Wildcard + "'"
oneDriveServiceCommandDeleteUseSuffix = " --backup <backupId>"
oneDriveServiceCommandDetailsUseSuffix = " --backup <backupId>"
)

const (
oneDriveServiceCommandCreateExamples = `# Backup OneDrive data for Alice
corso backup create onedrive --user [email protected]
# Backup OneDrive for Alice and Bob
corso backup create onedrive --user [email protected],[email protected]
# Backup all OneDrive data for all M365 users
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 [email protected]
# Explore Alice or Bob's files with name containing "Fiscal 22" in folder "Reports"
corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user [email protected],[email protected] --file-name "Fiscal 22" --folder "Reports"
# Explore Alice's files created before end of 2015 from a specific backup
corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
--user [email protected] --file-created-before 2015-01-01T00:00:00`
)

var (
folderPaths []string
fileNames []string
Expand All @@ -52,9 +77,10 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command {
c, fs = utils.AddCommand(parent, oneDriveCreateCmd())

c.Use = c.Use + oneDriveServiceCommandCreateUseSuffix
c.Example = utils.IndentExamples(oneDriveServiceCommandCreateExamples)

fs.StringArrayVar(&user, "user", nil,
"Backup OneDrive data by user ID; accepts "+utils.Wildcard+" to select all users. (required)")
"Backup OneDrive data by user ID; accepts '"+utils.Wildcard+"' to select all users. (required)")
options.AddOperationFlags(c)

case listCommand:
Expand All @@ -64,6 +90,7 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command {
c, fs = utils.AddCommand(parent, oneDriveDetailsCmd())

c.Use = c.Use + oneDriveServiceCommandDetailsUseSuffix
c.Example = utils.IndentExamples(oneDriveServiceCommandDetailsExamples)

fs.StringVar(&backupID, "backup", "", "ID of the backup to explore. (required)")
cobra.CheckErr(c.MarkFlagRequired("backup"))
Expand All @@ -73,37 +100,38 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command {
fs.StringSliceVar(
&folderPaths,
"folder", nil,
"Select backup details by OneDrive folder; defaults to root")
"Select backup details by OneDrive folder; defaults to root.")

fs.StringSliceVar(
&fileNames,
"file-name", nil,
"Select backup details by OneDrive file name")
"file", nil,
"Select backup details by file name or ID.")

// onedrive info flags

fs.StringVar(
&fileCreatedAfter,
"file-created-after", "",
"Select files created after this datetime")
"Select backup details for files created after this datetime.")
fs.StringVar(
&fileCreatedBefore,
"file-created-before", "",
"Select files created before this datetime")
"Select backup details for files created before this datetime.")

fs.StringVar(
&fileModifiedAfter,
"file-modified-after", "",
"Select files modified after this datetime")
"Select backup details for files modified after this datetime.")
fs.StringVar(
&fileModifiedBefore,
"file-modified-before", "",
"Select files modified before this datetime")
"Select backup details for files modified before this datetime.")

case deleteCommand:
c, fs = utils.AddCommand(parent, oneDriveDeleteCmd())

c.Use = c.Use + oneDriveServiceCommandDeleteUseSuffix
c.Example = utils.IndentExamples(oneDriveServiceCommandDeleteExamples)

fs.StringVar(&backupID, "backup", "", "ID of the backup to delete. (required)")
cobra.CheckErr(c.MarkFlagRequired("backup"))
Expand All @@ -119,10 +147,11 @@ func addOneDriveCommands(parent *cobra.Command) *cobra.Command {
// `corso backup create onedrive [<flag>...]`
func oneDriveCreateCmd() *cobra.Command {
return &cobra.Command{
Use: oneDriveServiceCommand,
Short: "Backup M365 OneDrive service data",
RunE: createOneDriveCmd,
Args: cobra.NoArgs,
Use: oneDriveServiceCommand,
Short: "Backup M365 OneDrive service data",
RunE: createOneDriveCmd,
Args: cobra.NoArgs,
Example: oneDriveServiceCommandCreateExamples,
}
}

Expand Down Expand Up @@ -234,10 +263,11 @@ func listOneDriveCmd(cmd *cobra.Command, args []string) error {
// `corso backup details onedrive [<flag>...]`
func oneDriveDetailsCmd() *cobra.Command {
return &cobra.Command{
Use: oneDriveServiceCommand,
Short: "Shows the details of a M365 OneDrive service backup",
RunE: detailsOneDriveCmd,
Args: cobra.NoArgs,
Use: oneDriveServiceCommand,
Short: "Shows the details of a M365 OneDrive service backup",
RunE: detailsOneDriveCmd,
Args: cobra.NoArgs,
Example: oneDriveServiceCommandDetailsExamples,
}
}

Expand Down Expand Up @@ -318,10 +348,11 @@ func runDetailsOneDriveCmd(
// `corso backup delete onedrive [<flag>...]`
func oneDriveDeleteCmd() *cobra.Command {
return &cobra.Command{
Use: oneDriveServiceCommand,
Short: "Delete backed-up M365 OneDrive service data",
RunE: deleteOneDriveCmd,
Args: cobra.NoArgs,
Use: oneDriveServiceCommand,
Short: "Delete backed-up M365 OneDrive service data",
RunE: deleteOneDriveCmd,
Args: cobra.NoArgs,
Example: oneDriveServiceCommandDeleteExamples,
}
}

Expand Down
42 changes: 32 additions & 10 deletions src/cli/repo/s3.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,18 +58,39 @@ const (
s3ProviderCommandUseSuffix = " --bucket <bucket>"
)

const (
s3ProviderCommandInitExamples = `# Create a new Corso repo in AWS S3 bucket named "my-bucket"
corso repo init s3 --bucket my-bucket
# Create a new Corso repo in AWS S3 bucket named "my-bucket" using a prefix
corso repo init s3 --bucket my-bucket --prefix my-prefix
# Create a new Corso repo in an S3 compliant storage provider
corso repo init s3 --bucket my-bucket --endpoint https://my-s3-server-endpoint`

s3ProviderCommandConnectExamples = `# Connect to a Corso repo in AWS S3 bucket named "my-bucket"
corso repo connect s3 --bucket my-bucket
# Connect to a Corso repo in AWS S3 bucket named "my-bucket" using a prefix
corso repo connect s3 --bucket my-bucket --prefix my-prefix
# Connect to a Corso repo in an S3 compliant storage provider
corso repo connect s3 --bucket my-bucket --endpoint https://my-s3-server-endpoint`
)

// ---------------------------------------------------------------------------------------------------------
// Init
// ---------------------------------------------------------------------------------------------------------

// `corso repo init s3 [<flag>...]`
func s3InitCmd() *cobra.Command {
return &cobra.Command{
Use: s3ProviderCommand,
Short: "Initialize a S3 repository",
Long: `Bootstraps a new S3 repository and connects it to your m356 account.`,
RunE: initS3Cmd,
Args: cobra.NoArgs,
Use: s3ProviderCommand,
Short: "Initialize a S3 repository",
Long: `Bootstraps a new S3 repository and connects it to your m356 account.`,
RunE: initS3Cmd,
Args: cobra.NoArgs,
Example: utils.IndentExamples(s3ProviderCommandInitExamples),
}
}

Expand Down Expand Up @@ -123,11 +144,12 @@ func initS3Cmd(cmd *cobra.Command, args []string) error {
// `corso repo connect s3 [<flag>...]`
func s3ConnectCmd() *cobra.Command {
return &cobra.Command{
Use: s3ProviderCommand,
Short: "Connect to a S3 repository",
Long: `Ensures a connection to an existing S3 repository.`,
RunE: connectS3Cmd,
Args: cobra.NoArgs,
Use: s3ProviderCommand,
Short: "Connect to a S3 repository",
Long: `Ensures a connection to an existing S3 repository.`,
RunE: connectS3Cmd,
Args: cobra.NoArgs,
Example: s3ProviderCommandConnectExamples,
}
}

Expand Down
Loading

0 comments on commit 3a1eb1e

Please sign in to comment.