> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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:

```bash theme={null}
cloudstic backup -source local:~/Documents
```

### Backup with Exclusions

Exclude temporary files and build artifacts:

```bash theme={null}
cloudstic backup -source local:~/Projects \
  -exclude "*.tmp" \
  -exclude "node_modules/" \
  -exclude ".git/" \
  -exclude "target/"
```

### Using an Exclude File

Create a `.backupignore` file:

```gitignore theme={null}
# .backupignore
*.tmp
*.log
.DS_Store
node_modules/
.git/
__pycache__/
```

Then reference it in your backup:

```bash theme={null}
cloudstic backup -source local:~/Projects \
  -exclude-file .backupignore
```

### Backup with Tags

Tag snapshots for easier identification:

```bash theme={null}
cloudstic backup -source local:~/Documents \
  -tag "documents" \
  -tag "daily"
```

### Dry Run

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

```bash theme={null}
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:

1. The relative path from the root is computed
2. Exclude patterns are applied
3. File metadata is collected (size, modified time, POSIX permissions, ownership, birth time, file flags, and extended attributes)
4. 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](#portable-drives) for details.

## Exclude Patterns

Exclude patterns use gitignore syntax:

### Pattern Examples

<CodeGroup>
  ```bash File Extensions theme={null}
  # Exclude all temporary files
  -exclude "*.tmp"
  -exclude "*.log"
  -exclude "*.cache"
  ```

  ```bash Directories theme={null}
  # Exclude entire directories
  -exclude "node_modules/"
  -exclude ".git/"
  -exclude "__pycache__/"
  ```

  ```bash Specific Files theme={null}
  # Exclude specific files anywhere
  -exclude ".DS_Store"
  -exclude "Thumbs.db"
  ```

  ```bash Path Patterns theme={null}
  # Exclude files in specific locations
  -exclude "temp/"
  -exclude "build/"
  -exclude "dist/"
  ```
</CodeGroup>

### 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 `!`:

```bash theme={null}
# Exclude all .log files except important.log
-exclude "*.log"
-exclude "!important.log"
```

## Symbolic Links

<Warning>
  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.
</Warning>

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

<Steps>
  <Step title="Use exclude patterns">
    Exclude unnecessary directories to reduce scan time:

    ```bash theme={null}
    -exclude "node_modules/" -exclude ".git/"
    ```
  </Step>

  <Step title="Enable packfiles">
    Packfiles bundle small objects to reduce store overhead and are enabled by default. No flag needed.
  </Step>

  <Step title="Avoid remote mounts">
    Back up from local storage rather than network mounts when possible.
  </Step>
</Steps>

## Common Use Cases

### Personal Documents

```bash theme={null}
cloudstic backup -source local:~/Documents \
  -exclude ".DS_Store" \
  -tag "documents"
```

### Development Projects

```bash theme={null}
cloudstic backup -source local:~/Projects \
  -exclude "node_modules/" \
  -exclude ".git/" \
  -exclude "target/" \
  -exclude "build/" \
  -tag "projects"
```

### System Configuration

```bash theme={null}
cloudstic backup -source local:/etc \
  -tag "config" \
  -tag "$(hostname)"
```

### Photo Library

```bash theme={null}
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:

```bash theme={null}
# 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"
```

<Info>
  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.
</Info>

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` |

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## Troubleshooting

### Permission Denied

If you encounter permission errors:

```bash theme={null}
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:

```bash theme={null}
# Check estimated backup size
cloudstic backup -source local:~/Documents -dry-run
```

### Path Not Found

If the source path doesn't exist:

```bash theme={null}
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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="SFTP Source" icon="server" href="/sources/sftp">
    Learn about backing up remote servers
  </Card>

  <Card title="Restore Files" icon="download" href="/commands/restore">
    Learn how to restore your backed up files
  </Card>

  <Card title="Exclude Patterns" icon="filter" href="/commands/backup#exclude-patterns">
    Master exclude pattern syntax
  </Card>

  <Card title="Incremental Backups" icon="clock" href="/commands/backup#incremental-backups">
    Understand how incremental backups work
  </Card>
</CardGroup>