tree-fs

tree-fs is a Rust library designed to simplify the creation and management of temporary file system structures. Its core feature is creating directories and files programmatically, which are automatically cleaned up when the managing object goes out of scope. This makes it ideal for scenarios where you need a predictable, temporary workspace, such as testing, build processes, or data generation tasks.

Why tree-fs?

Manually creating and cleaning up temporary file structures can be cumbersome and error-prone. You might need to:

• Create specific directory layouts.
• Populate files with predefined content.
• Ensure files have particular permissions (e.g., a config file that should be read-only).
• Reliably clean up all temporary files and directories afterwards.

tree-fs automates these tasks, making your code cleaner and more reliable. Consider these use cases:

• Testing: Set up fixtures for tests that interact with the file system, ensuring a clean state for each test run.
• Configuration Management: Applications that load settings from files (e.g., config/app.json) can use tree-fs to generate temporary config files for specific runs.
• Temporary Workspaces: Create a temporary space for data processing, intermediate file generation, or running external tools that expect a certain directory structure.
• Build Scripts & Scaffolding: Generate temporary project structures or configuration files needed during a build process or for code generation tasks.
• Permissions Handling: Create files with specific permissions (like read-only) to test or simulate real-world scenarios.

Features

• Fluent Builder API: Programmatically define your file tree.
• YAML Configuration: Define trees using YAML files or strings (requires the yaml feature).
• Temporary Directories: Trees are typically created in a system temporary folder.
• Automatic Cleanup: Temporary trees are automatically deleted when the Tree instance goes out of scope (this can be disabled).
• File Contents: Easily specify text content for files.
• Empty Files & Directories: Create empty files or entire directory structures.
• File Settings: Set file attributes, such as read-only permissions.

Installation

Add tree-fs to your Cargo.toml:

[dependencies]
tree-fs = "0.3" # Replace with the latest version

Usage

1. Using the Builder API

The TreeBuilder provides a fluent interface to construct your desired file system structure.

use tree_fs::{TreeBuilder, Settings};
let tree = TreeBuilder::default()
    .add_file("config/app.conf", "host = localhost")
    .add_empty_file("logs/app.log")
    .add_directory("data/raw")
    .add_file_with_settings(
        "secrets/api.key",
        "supersecretkey",
        Settings::new().readonly(true)
    )
    .create()
    .expect("create tree fs");
println!("Created a complex tree in: {}", tree.root.display());

// You can verify the readonly status (this requires std::fs)
// let key_path = tree.root.join("secrets/api.key");
// let metadata = std::fs::metadata(key_path).unwrap();
// assert!(metadata.permissions().readonly());

For a more comprehensive example covering custom root directories, overriding files, and various file types, see examples/builder.rs.

You can disable this behavior using .drop(false) on the builder if you need the files to persist.

2. Using YAML (requires the yaml feature)

To use YAML, enable the yaml feature for tree-fs in your Cargo.toml.

From a YAML File

You can define your file tree in a YAML file. This is useful for complex or reusable structures.

Example tests/fixtures/tree.yaml:

override_file: false
entries:
  - path: foo.json
    type: text_file
    content: |
      { "foo": "bar" }
  - path: folder/bar.yaml
    type: text_file
    content: |
      foo: bar
  - path: readonly_config.ini
    type: text_file
    content: |
      ; Sample read-only INI file
      [general]
      setting = value
    settings:
      readonly: true

Rust code to load the YAML file:

See the example file examples/yaml-file.rs for how to load this structure using tree_fs::from_yaml_file.

From a YAML String

For simpler or inline definitions, you can provide the YAML structure as a string.

See the example file examples/yaml-str.rs for how to load a structure from a YAML string using tree_fs::from_yaml_str, including defining settings like readonly.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.