feat: cloud subdirectory backup (RFC 0007)

[rmanibus]

Summary

Implement RFC 0007 by supporting cloud backup roots scoped to subdirectories (Google Drive / OneDrive), including incremental-source behavior.

What Changes

• Backup/source parsing updates for cloud source root path handling.
• Google Drive updates:
  • root path resolution and subdirectory-aware traversal
  • change-source handling aligned with selected subpath root
• OneDrive updates:
  • subdirectory root handling in regular and change-based sources
• CLI/help/docs updates for source URI/path semantics.
• RFC update and tests for path/root behavior.

Files of Interest

• pkg/source/gdrive.go
• pkg/source/gdrive_changes.go
• pkg/source/onedrive.go
• pkg/source/onedrive_changes.go
• cmd/cloudstic/cmd_backup.go
• rfcs/0007-cloud-subdirectory-backup.md

Behavior Notes

• Cloud sources can target a nested root path while preserving stable source identity and incremental scan behavior.
• Errors are clearer for invalid/unresolvable cloud root paths.

Tracking

• Story / epic: RFC 0007: Epic / Tracking issue for cloud subdirectory backup #100
• RFC: rfcs/0007-cloud-subdirectory-backup.md
• Milestone: RFC 0007: Cloud subdirectory backup

Housekeeping

• If merge artifact files are still present (*.orig, *.rej), they should be removed before merge.

[codecov]

Codecov Report

❌ Patch coverage is 31.91489% with 128 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/source/gdrive.go	1.42%	69 Missing ⚠️
pkg/source/gdrive_changes.go	41.66%	30 Missing and 5 partials ⚠️
pkg/source/onedrive.go	6.66%	14 Missing ⚠️
pkg/source/onedrive_changes.go	76.92%	6 Missing ⚠️
cmd/cloudstic/cmd_backup.go	33.33%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Implements RFC 0007 by allowing Google Drive and OneDrive sources to scope backup roots to a subdirectory path (via -source <scheme>:<path>), while preserving incremental/change-source behavior and updating CLI parsing + documentation accordingly.

Changes:

• Extend -source parsing to accept optional [:<path>] for cloud schemes and default cloud roots to "/".
• Add root-path support to Google Drive and OneDrive sources (full scans and incremental/change scans), including root-aware filtering/traversal.
• Update docs/RFC/help/completions and add/adjust tests for new root path semantics.

Reviewed changes

Copilot reviewed 18 out of 23 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
rfcs/0007-cloud-subdirectory-backup.md	Adds RFC text describing the new cloud subdirectory backup behavior and CLI syntax.
pkg/source/gdrive.go	Adds rootPath option, resolves path→folderID, and filters traversal to a sub-root.
pkg/source/gdrive_changes.go	Refactors change processing to resolve paths and filter changes to a sub-root.
pkg/source/gdrive_changes_test.go	Adds tests for rooted change processing behavior.
pkg/source/gdrive_test.go	Updates SourceInfo.Path expectations to use human paths (not IDs).
pkg/source/onedrive.go	Adds rootPath option and scopes Graph traversal to a sub-root.
pkg/source/onedrive_changes.go	Scopes delta token + emitted changes to a sub-root via root path filtering.
pkg/source/onedrive_test.go	Updates Info tests and adds a unit test for rooted change filtering.
pkg/source/onedrive_test.go.orig	Merge artifact added to PR (should be removed).
pkg/source/onedrive_test.go.rej	Merge artifact added to PR (should be removed).
cmd/cloudstic/store.go	Extends parseSourceURI to parse cloud schemes with optional paths and defaults cloud roots to "/".
cmd/cloudstic/store_test.go	Updates/extends tests to cover cloud paths and default root behavior.
cmd/cloudstic/cmd_backup.go	Wires parsed cloud root paths into source constructors; updates -source help text.
cmd/cloudstic/usage.go	Removes -root-folder from usage output (but help text still needs updating for new syntax).
docs/user-guide.md	Updates user guide examples/flags to use gdrive[:<path>] and removes -root-folder.
docs/sources.md	Updates gdrive scoping description (but SourceInfo.Path table still needs updating).
cmd/cloudstic/completion.go	Removes -root-folder from shell completions.
cmd/cloudstic/flags.go	Formatting-only changes.
cmd/cloudstic/cmd_forget_test.go	Formatting-only change (newline).
pkg/source/local_source_plist_test.go	Formatting-only changes.
e2e/portable_stub.go	Formatting-only changes.
e2e/portable_darwin.go	Formatting-only changes.
.gitignore	Adds .opencode/ ignore and normalizes .DS_Store line.

Comments suppressed due to low confidence (1)

cmd/cloudstic/usage.go:132

• The usage text for -source and the subsequent "Source URI formats" list still documents cloud sources as bare keywords only (gdrive, onedrive, etc.). Since parseSourceURI now supports cloud paths (e.g. gdrive:/path, onedrive:/path), update these help strings to reflect the new [:] syntax and examples (including "/" as the explicit root).

	t.Flags([][2]string{
		{"-source <uri>", ui.Env("Source URI: local:<path>, sftp://[user@]host[:port]/<path>, gdrive, gdrive-changes, onedrive, onedrive-changes", "CLOUDSTIC_SOURCE")},
		{"-drive-id <id>", "Shared drive ID for gdrive (omit for My Drive)"},
		{"-skip-native-files", "Exclude Google-native files (Docs, Sheets, Slides, etc.)"},
		{"-google-credentials <path>", ui.Env("Path to Google service account credentials JSON", "GOOGLE_APPLICATION_CREDENTIALS")},
		{"-google-token-file <path>", ui.Env("Path to Google OAuth token file", "GOOGLE_TOKEN_FILE")},
		{"-onedrive-client-id <id>", ui.Env("OneDrive OAuth client ID", "ONEDRIVE_CLIENT_ID")},
		{"-onedrive-token-file <path>", ui.Env("Path to OneDrive OAuth token file", "ONEDRIVE_TOKEN_FILE")},
		{"-tag <tag>", "Tag to apply to the snapshot (repeatable)"},
		{"-exclude <pattern>", "Exclude pattern, gitignore syntax (repeatable)"},
		{"-exclude-file <path>", "Load exclude patterns from file (one per line, gitignore syntax)"},
		{"-dry-run", "Scan source and report changes without writing to the store"},
	})
	t.Blank()
	t.Note(
		"Source URI formats:",
		"  local:<path>                       e.g. local:./documents",
		"  sftp://[user@]host[:port]/<path>   e.g. sftp://backup@host.com/data",
		"  gdrive                             Google Drive (full scan)",
		"  gdrive-changes                     Google Drive (incremental via Changes API)",
		"  onedrive                           OneDrive (full scan)",
		"  onedrive-changes                   OneDrive (incremental via delta API)",
	)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.