Local Directory Source

Back up files from your local filesystem with Cloudstic CLI

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 local	Specifies 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-run	Scan 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

Backup with Tags

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:

1. The relative path from the root is computed
2. Exclude patterns are applied
3. File metadata is collected (size, modified time)
4. 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

Source Information

Each snapshot records:

• Type: local
• Account: 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

# 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.

Performance Considerations

Fast Operations

The local source is the fastest because:

• No network overhead
• Direct filesystem access
• Efficient file metadata retrieval

Typical Performance

On modern hardware:

• Scanning: 10,000+ files/second
• Backup speed: Limited by storage and encryption overhead
• Incremental backups: Only changed files are uploaded

Optimizing Performance

1. Use exclude patterns

   Exclude unnecessary directories to reduce scan time:

   -exclude "node_modules/" -exclude ".git/"
   
2. Enable packfiles

   Bundle small objects to reduce store overhead (enabled by default):

   -enable-packfile
   
3. 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

SFTP Source

Learn about backing up remote servers

Restore Files

Learn how to restore your backed up files

Exclude Patterns

Master exclude pattern syntax

Incremental Backups

Understand how incremental backups work