The local source backs up files and directories from your local filesystem. This is the simplest source type and provides the fastest backup performance.
Basic Usage Back up a local directory:
cloudstic backup -source local -source-path /path/to/directory
The source will recursively scan all files and folders under the specified path.
Configuration Options Required Flags Flag Description -source localSpecifies the local filesystem source -source-path <path>Path to the directory to back up
Optional Flags Flag Description -exclude <pattern>Exclude pattern (gitignore syntax, repeatable) -exclude-file <path>Load exclude patterns from file -tag <tag>Tag to apply to the snapshot (repeatable) -dry-runScan source without writing to store
Examples Basic Backup Back up your documents folder:
cloudstic backup -source local -source-path ~/Documents
Backup with Exclusions Exclude temporary files and build artifacts:
cloudstic backup -source local -source-path ~/Projects \ -exclude "*.tmp" \ -exclude "node_modules/" \ -exclude ".git/" \ -exclude "target/"
Using an Exclude File Create a .backupignore file:
# .backupignore *.tmp *.log .DS_Store node_modules/ .git/ __pycache__/
Then reference it in your backup:
cloudstic backup -source local -source-path ~/Projects \ -exclude-file .backupignore
Tag snapshots for easier identification:
cloudstic backup -source local -source-path ~/Documents \ -tag "documents" \ -tag "daily"
Dry Run See what would be backed up without actually creating a snapshot:
cloudstic backup -source local -source-path ~/Documents -dry-run
How It Works File Scanning The local source uses Go’s filepath.Walk to recursively traverse the directory tree. For each file and folder:
The relative path from the root is computed
Exclude patterns are applied
File metadata is collected (size, modified time)
The entry is passed to the backup engine
File Identification Local files are identified by their relative path from the source root. For example:
Source path: /home/user/Documents
File: /home/user/Documents/report.pdf
File ID: report.pdf
For nested files:
File: /home/user/Documents/Projects/README.md
File ID: Projects/README.md
Each snapshot records:
Type : localAccount : Machine hostname (e.g., mycomputer.local)Path : Absolute path to the backup directory (e.g., /home/user/Documents)
Exclude Patterns Exclude patterns use gitignore syntax:
Pattern Examples File Extensions
Directories
Specific Files
Path Patterns
# Exclude all temporary files -exclude "*.tmp" -exclude "*.log" -exclude "*.cache"
Wildcard Syntax
* — Matches any number of characters except /** — Matches any number of characters including /? — Matches a single character[abc] — Matches one character from the set[a-z] — Matches one character from the range
Negation You can re-include files using !:
# Exclude all .log files except important.log -exclude "*.log" -exclude "!important.log"
Symbolic Links Symbolic links are not followed by the local source. If you need to back up the target of a symbolic link, back up the target directory directly.
Fast Operations The local source is the fastest because:
No network overhead
Direct filesystem access
Efficient file metadata retrieval
On modern hardware:
Scanning : 10,000+ files/secondBackup speed : Limited by storage and encryption overheadIncremental backups : Only changed files are uploaded
Use exclude patterns
Exclude unnecessary directories to reduce scan time: -exclude "node_modules/" -exclude ".git/"
Enable packfiles
Bundle small objects to reduce store overhead (enabled by default):
Avoid remote mounts
Back up from local storage rather than network mounts when possible.
Common Use Cases Personal Documents cloudstic backup -source local -source-path ~/Documents \ -exclude ".DS_Store" \ -tag "documents"
Development Projects cloudstic backup -source local -source-path ~/Projects \ -exclude "node_modules/" \ -exclude ".git/" \ -exclude "target/" \ -exclude "build/" \ -tag "projects"
System Configuration cloudstic backup -source local -source-path /etc \ -tag "config" \ -tag "$( hostname )"
Photo Library cloudstic backup -source local -source-path ~/Pictures \ -exclude "*.tmp" \ -exclude ".picasaoriginals/" \ -tag "photos"
Troubleshooting Permission Denied If you encounter permission errors:
Error: permission denied: /path/to/file
Solutions:
Run Cloudstic with appropriate permissions
Exclude directories you don’t have access to
Use sudo if backing up system directories
Disk Space For large backups, ensure you have sufficient disk space:
# Check estimated backup size cloudstic backup -source local -source-path ~/Documents -dry-run
Path Not Found If the source path doesn’t exist:
Error: stat /path/to/directory: no such file or directory
Solutions:
Verify the path is correct
Use absolute paths to avoid ambiguity
Check that the directory exists before running backup
Environment Variables Set default values using environment variables:
export CLOUDSTIC_SOURCE = local export CLOUDSTIC_SOURCE_PATH = / home / user / Documents # Now you can run backup without flags cloudstic backup
Next Steps