# Obsidian Tools

A PyQt6 GUI application for aggregating and splitting Obsidian markdown files.

## Features

- **Aggregator**: Combine multiple `.md` files from a directory (including subdirectories) into a single aggregated file
- **Splitter**: Extract individual `.md` files from an aggregated file, preserving the original directory structure
- Clean, minimal tabbed interface
- Progress tracking during operations
- Linux support

## Requirements

- Python 3.8 or higher
- PyQt6

## Installation

The virtual environment is already set up and dependencies are installed.

## Usage

Run the application:
```bash
./run.sh
```

### Desktop Launcher (Quick Access)

Per avviare rapidamente dalla Scrivania, usa lo script helper:

```bash
./create-desktop-link.sh
```

Questo creerà un file `ObsidianTools.desktop` sulla tua Scrivania.

**Prima volta:** Potrebbe essere necessario fare click destro sul file e selezionare "Fidati ed esegui" o "Allow Launching" per autorizzarlo.

Successivamente, basta un doppio click su "ObsidianTools.desktop" per avviare l'applicazione.

## How to Use

### Aggregator Tab

1. Click "Browse..." next to "Source Directory" and select the folder containing your `.md` files
2. Click "Browse..." next to "Output File" and choose where to save the aggregated file
3. Click "Aggregate Files" to combine all markdown files
4. A progress bar will show the operation status
5. Upon completion, you'll see a success message with statistics

### Splitter Tab

1. Click "Browse..." next to "Aggregated File" and select the aggregated `.md` file
2. Click "Browse..." next to "Output Directory" and choose where to extract the files
3. Click "Split Files" to extract all individual files
4. A progress bar will show the operation status
5. Upon completion, you'll see a success message with statistics

## File Format Specification

### Aggregated File Structure

The aggregated file uses a simple separator format to mark file boundaries:

```
--- FILE: relative/path/file1.md ---
[Content of file1.md]

--- FILE: relative/path/file2.md ---
[Content of file2.md]

--- FILE: subfolder/file3.md ---
[Content of file3.md]
```

**Format Rules:**
- Each file section starts with: `--- FILE: <relative-path> ---`
- The separator must be on its own line
- Relative paths use forward slashes `/` for cross-platform compatibility
- Paths are relative to the source directory
- File encoding is UTF-8
- Content between separators belongs to that file

## Project Structure

```
ObsidianTool/
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── .gitignore                  # Git ignore rules
├── run.sh                      # Run script
├── venv/                       # Virtual environment
├── src/
│   ├── __init__.py
│   ├── main.py                 # Application entry point
│   ├── gui/
│   │   ├── __init__.py
│   │   ├── main_window.py      # Main window with tabs
│   │   ├── aggregator_tab.py   # Aggregator tab
│   │   └── splitter_tab.py     # Splitter tab
│   └── core/
│       ├── __init__.py
│       ├── aggregator.py       # Aggregation logic
│       ├── splitter.py         # Splitting logic
│       └── exceptions.py       # Custom exceptions
└── tests/                       # Future test directory
    └── __init__.py
```

## Development

### Manual Installation

If you prefer to set up manually:

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate.bat  # Windows

# Install dependencies
pip install -r requirements.txt

# Run application
python src/main.py
```

## Error Handling

The application includes robust error handling for common scenarios:

- Invalid directory or file paths
- Permission issues
- Encoding errors
- Invalid file format
- Disk space issues

Error messages are displayed in dialog boxes with clear explanations.

## Use Cases

- **Backup**: Aggregate all notes into a single file for backup purposes
- **Version Control**: Create a single file for easier version control
- **Migration**: Export notes from one vault structure and import into another
- **Sharing**: Share a collection of notes as a single file
- **Archiving**: Archive project notes while preserving structure

## License

This project is open source. Feel free to use and modify as needed.

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Troubleshooting

### "No module named PyQt6" error
Reinstall dependencies:
```bash
venv/bin/pip install -r requirements.txt
```

### Application won't start
Make sure you're using Python 3.8 or higher:
```bash
python --version
```

### Files not showing up in aggregation
- Ensure files have `.md` extension
- Check that the source directory path is correct
- Verify you have read permissions for the directory

### Split operation creates empty files
- Check that the aggregated file uses the correct separator format
- Ensure the file is UTF-8 encoded
- Verify the file hasn't been corrupted

## Contact

For bugs or feature requests, please open an issue on the project repository.