Local Directory Source - 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:/path/to/directory

The source will recursively scan all files and folders under the specified path.

Configuration Options

Required Flags

Flag	Description
`-source local:<path>`	Specifies the local filesystem source and path 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)
`-volume-uuid <uuid>`	Override volume UUID for portable drive identity
`-dry-run`	Scan source without writing to store

Examples

Basic Backup

Back up your documents folder:

cloudstic backup -source local:~/Documents

Backup with Exclusions

Exclude temporary files and build artifacts:

cloudstic backup -source local:~/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:~/Projects \
  -exclude-file .backupignore

Backup with Tags

Tag snapshots for easier identification:

cloudstic backup -source local:~/Documents \
  -tag "documents" \
  -tag "daily"

Dry Run

See what would be backed up without actually creating a snapshot:

cloudstic backup -source local:~/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, POSIX permissions, ownership, birth time, file flags, and extended attributes)
The entry is passed to the backup engine

Extended File Attributes

On macOS and Linux, Cloudstic captures additional POSIX metadata for each file:

Attribute	macOS	Linux	SFTP
Permissions (mode)	✅	✅	✅
Ownership (uid/gid)	✅	✅	✅
Birth time (btime)	✅ (always)	✅ (kernel ≥ 4.11, filesystem dependent)	❌
File flags	✅ (UF_/SF_)	✅ (FS_*_FL via ioctl)	❌
Extended attributes	✅	✅	❌

You can control what is collected with these flags:

Flag	Description
`-skip-mode`	Skip all POSIX metadata (mode, uid, gid, btime, flags)
`-skip-flags`	Skip file flags only (avoids extra file descriptor per entry on Linux)
`-skip-xattrs`	Skip extended attribute collection
`-xattr-namespaces`	Comma-separated prefixes to collect (e.g. `user.,com.apple.`)

On Windows, extended attributes are not collected (fields are omitted from snapshots). Cloudstic also excludes a small set of known OS-managed xattrs that are not meaningfully restorable, such as com.apple.provenance on macOS.

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)
Volume UUID: Filesystem volume UUID, auto-detected on macOS and Linux (optional)
Volume label: Human-readable volume name (optional)

For portable and external drives, the volume UUID is used instead of hostname and path to identify the backup source. This enables true incremental backups when the same drive is backed up from different machines. See Portable drives for details.

Exclude Patterns

Exclude patterns use gitignore syntax:

Pattern Examples

# 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

Use exclude patterns

Exclude unnecessary directories to reduce scan time:

-exclude "node_modules/" -exclude ".git/"

Enable packfiles

Packfiles bundle small objects to reduce store overhead and are enabled by default. No flag needed.

Avoid remote mounts

Back up from local storage rather than network mounts when possible.

Common Use Cases

Personal Documents

cloudstic backup -source local:~/Documents \
  -exclude ".DS_Store" \
  -tag "documents"

Development Projects

cloudstic backup -source local:~/Projects \
  -exclude "node_modules/" \
  -exclude ".git/" \
  -exclude "target/" \
  -exclude "build/" \
  -tag "projects"

System Configuration

cloudstic backup -source local:/etc \
  -tag "config" \
  -tag "$(hostname)"

Photo Library

cloudstic backup -source local:~/Pictures \
  -exclude "*.tmp" \
  -exclude ".picasaoriginals/" \
  -tag "photos"

Portable Drives

Back up a portable or external drive with automatic cross-machine incremental support:

# Volume UUID is auto-detected on macOS and Linux
cloudstic backup -source local:/Volumes/MyDrive

# Override UUID when auto-detection is unavailable
cloudstic backup -source local:/mnt/backup \
  -volume-uuid "A1B2C3D4-1234-5678-ABCD-EF0123456789"

When you back up a portable drive from machine A, then plug it into machine B and back up again, Cloudstic uses the volume UUID to find the previous snapshot even though the hostname and mount point are different. Only changed files are uploaded.

File paths inside the backup are normalized to forward slashes regardless of the operating system, so a backup started on one OS can be continued incrementally on another. The volume UUID detection prioritizes the GPT partition UUID (stable across operating systems) over platform-specific UUIDs. For modern GPT-formatted drives, cross-OS incremental backups work automatically. Platform support:

Platform	UUID detection	Label detection
macOS	✓ Automatic (GPT partition UUID via `diskutil`, fallback to `getattrlist`)	✓ Automatic
Linux	✓ Automatic (GPT partition UUID via `/dev/disk/by-partuuid/`, fallback to `/dev/disk/by-uuid/`)	✓ Automatic (`/dev/disk/by-label/`)
Windows	✓ Automatic (GPT partition UUID via `DeviceIoControl`)	✓ Automatic (`GetVolumeInformation`)

Cross-OS compatibility:

Drive format	macOS ↔ Linux	macOS/Linux ↔ Windows
GPT (exFAT, APFS, ext4)	✓ Automatic	✓ Automatic
MBR (older FAT32)	Requires `-volume-uuid`	Requires `-volume-uuid`

Retention policies automatically group all snapshots of the same volume together across machines. A -keep-daily 7 policy keeps 7 daily snapshots total, regardless of which machine created them.

The volume UUID is determined from the backup root path only. If your backup directory contains mount points for other volumes (e.g. /data/external is a separate partition mounted under /data), those files are included in the backup but the volume identity reflects only the root path’s filesystem. For portable drive workflows, back up each volume separately rather than backing up a parent directory that spans multiple drives. Note that symlinks to other volumes are not followed. Only direct mount points within the tree are traversed.

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:~/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:/home/user/Documents

# Override volume UUID for portable drives
export CLOUDSTIC_VOLUME_UUID="A1B2C3D4-1234-5678-ABCD-EF0123456789"

# 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

Get Started

Core Concepts

Sources

Storage Backends

Guides

​Basic Usage

​Configuration Options

​Required Flags

​Optional Flags

​Examples

​Basic Backup

​Backup with Exclusions

​Using an Exclude File

​Backup with Tags

​Dry Run

​How It Works

​File Scanning

​Extended File Attributes

​File Identification

​Source Information

​Exclude Patterns

​Pattern Examples

​Wildcard Syntax

​Negation

​Symbolic Links

​Performance Considerations

​Fast Operations

​Typical Performance

​Optimizing Performance

​Common Use Cases

​Personal Documents

​Development Projects

​System Configuration

​Photo Library

​Portable Drives

​Troubleshooting

​Permission Denied

​Disk Space

​Path Not Found

​Environment Variables

​Next Steps

SFTP Source

Restore Files

Exclude Patterns

Incremental Backups

Basic Usage

Configuration Options

Required Flags

Optional Flags

Examples

Basic Backup

Backup with Exclusions

Using an Exclude File

Backup with Tags

Dry Run

How It Works

File Scanning

Extended File Attributes

File Identification

Source Information

Exclude Patterns

Pattern Examples

Wildcard Syntax

Negation

Symbolic Links

Performance Considerations

Fast Operations

Typical Performance

Optimizing Performance

Common Use Cases

Personal Documents

Development Projects

System Configuration

Photo Library

Portable Drives

Troubleshooting

Permission Denied

Disk Space

Path Not Found

Environment Variables

Next Steps