Skip to content

[docs] Document inventory filtering and exclusion behaviors #270

@paul-fresquet

Description

@paul-fresquet

Summary

Document the file filtering and exclusion behaviors in ByteSync, explaining what types of entries are excluded, why, and on which platforms.

Background

ByteSync filters various filesystem entries during inventory building. This behavior should be documented for:

  • End users who want to understand why files don't appear
  • Contributors who need to understand the filtering logic
  • Future maintainers

Proposed Documentation

Create or update documentation covering:

1. Entry Types and Handling

Entry Type Behavior Platforms User Configurable
Regular files Included All No
Directories Traversed All No
Symbolic links Excluded All No
Block devices Excluded Linux/macOS No
Character devices Excluded Linux/macOS No
FIFOs Excluded Linux/macOS No
Unix sockets Excluded Linux/macOS No
Hidden files Excluded (optional) All Yes
Noise files Excluded (optional) All Yes

2. Noise Files List

Document all files in the noise list with their platform and purpose.

3. Protected Paths

Document paths that cannot be used as data sources (/dev, /proc, etc.).

4. Platform-Specific Behaviors

  • Windows: FileAttributes.System, FileAttributes.Offline, ReparsePoint
  • macOS: Dot-files as hidden, resource forks
  • Linux: Dot-files as hidden, special filesystems

Proposed Location

Option A: docs/inventory-filtering.md (new file)
Option B: Section in existing README.md
Option C: Section in docs/synchronization-rules.md

Acceptance Criteria

  • Document all entry types and their handling
  • List all noise files with explanations
  • Explain protected paths
  • Document platform-specific behaviors
  • Include examples where helpful
  • Keep documentation in sync with code (add note about maintenance)

Content Outline

# Inventory Filtering and Exclusions

## Overview
ByteSync filters certain filesystem entries during inventory...

## Entry Classification
### Regular Files
### Directories  
### Symbolic Links
### POSIX Special Files

## Noise Files
### Windows
### macOS
### Linux

## Protected Paths

## Platform-Specific Behavior
### Windows
### macOS
### Linux

## User Settings
- Exclude hidden files
- Exclude system/noise files

Priority

Nice to Have — Improves user understanding and maintainability.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions