particle

Particle

Particle is a Go-based tool designed to enhance Syncthing's ignore patterns functionality. It addresses the need for more complex ignore rules, particularly for development projects using various programming languages and frameworks.

How It Works

Particle scans specified directories and applies a series of ignore pattern checks based on the project type. It generates .stignore files that are compatible with Syncthing, allowing for more granular control over which files and directories are synchronized.

Particle does not overwrite existing .stignore files. It will append new ignore patterns to the existing ones.

Supported Project Types

Particle automatically detects the following project types and adds relevant ignore patterns:

• Rust: Detects Cargo.toml and Cargo.lock. Ignores the target directory.
• Node.js: Detects package.json and node_modules. Ignores node_modules and dist directories.
• Dart/Flutter: Detects pubspec.yaml and pubspec.lock. Ignores the build directory.
• Python:
  • Detects requirements.txt or pyproject.toml. Ignores __pycache__, venv, .venv, build, dist.
  • Detects and ignores .conda directories.
• Android (Gradle): Detects build.gradle or build.gradle.kts. Ignores the build directory.
• Java (Maven): Detects pom.xml. Ignores the target directory.
• C/C++ (CMake): Detects CMakeLists.txt. Ignores the build directory.

Installation

To install Particle, use the following Go command:

go install github.com/doraemonkeys/particle@latest

Or you can download the binary from here, and put it in your PATH.

Usage

• Basic usage (local directory):

  particle -dir "/path/to/your/.stignore directory"
  

• Using with Syncthing Web API:

  particle -web -host http://127.0.0.1:8384 -user youruser
  

Flags:

• -dir: Target directory (for local scanning)
• -web: Get all directories from Syncthing Web API
• -host: Syncthing host (default: http://127.0.0.1:8384)
• -user: Syncthing user
• -pwdFile: Path to file containing Syncthing password
• -syncthing: Path to Syncthing executable file (used for resolving relative paths)

Web Interface

When using the -web flag, Particle will connect to your Syncthing instance and fetch all shared directories. It will then generate appropriate .stignore files for each directory based on its content.

Configuration

Particle uses environment variables and command-line flags for configuration. The Syncthing password can be provided via:

1. A password file (specified with -pwdFile)
2. The SYNCTHING_PASSWORD environment variable
3. Interactive prompt (if not provided by other means)

Customizing Rules

You can easily add or modify rules by editing the rule.go file in the source code. All rules are defined as functions and registered in a central list.

1. Open rule.go and define your checker function. A checker function has the signature func(dir string, entry []os.DirEntry) []string. It receives the directory path and a list of its entries. It should return a slice of patterns to ignore if the project type is detected, or nil otherwise.

   For example, to add a rule for Go projects:

   // Ignore Go build artifacts
   // If it contains go.mod, it is considered a Go project
   var GoProjectStIgnoreChecker = func(_ string, entry []os.DirEntry) []string {
       for _, v := range entry {
           if v.Name() == "go.mod" {
               // Return a list of patterns to ignore
               return []string{"vendor", "*.exe"}
           }
       }
       // Return nil if this is not a Go project
       return nil
   }
   

2. Add your new function to StIgnoreCheckList in rule.go:

   var StIgnoreCheckList = []StIgnoreCheckFunc{
       // ... existing checkers
       GoProjectStIgnoreChecker, // Add your new checker here
   }
   

3. Recompile the source code:

   go build
   

   You can now use the newly built particle executable with your custom rules.

Contributing

Contributions to Particle are welcome! Please feel free to submit pull requests, report bugs, or suggest new features through the GitHub issue tracker.

Acknowledgments

This project was inspired by the need for more complex ignore patterns in Syncthing, as discussed in Syncthing Issue #6195.