# tagitmd

CLI tool to add tags to markdown frontmatter.

## What it does

`tagitmd` scans markdown files in a directory and adds tags to their YAML frontmatter. It intelligently handles existing frontmatter, creating it if needed, and can optionally skip files that already have tags. You can also specify the path and disable recursion.

## Installation

```bash
pip install -e .
```

## Usage

```bash
tagitmd TAG [TAG...] [OPTIONS]
```

### Examples

```bash
# Add tags to all markdown files in current directory
tagitmd python tutorial

# Add tags to files in a specific directory
tagitmd python --path /path/to/notes

# Preview changes without modifying files
tagitmd python tutorial --dry-run

# Only add tags to files that don't have any tags yet
tagitmd python --only-untagged

# Process only the target directory (not subdirectories)
tagitmd python --no-recursive
```

## Flags

### `--path`, `-p`
- **Type**: Directory path
- **Default**: Current directory (`.`)
- **Description**: Directory to process for markdown files

### `--dry-run`
- **Type**: Flag
- **Default**: False
- **Description**: Preview changes without modifying any files. Shows what would be changed.

### `--only-untagged`
- **Type**: Flag
- **Default**: False
- **Description**: Only modify files that don't have any existing tags in their frontmatter

### `--recursive` / `--no-recursive`
- **Type**: Boolean flag
- **Default**: True (recursive)
- **Description**: Whether to search subdirectories recursively

## Development Guide

### Setup

Run the setup script to create a virtual environment and install dependencies:

```bash
bash setup-dev.sh
```

Or use Make:

```bash
make setup-dev
```

### Manual Setup

If you prefer to set up manually:

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

# Activate virtual environment
source venv/bin/activate

# Install package in development mode
pip install -e .

# Install development dependencies
pip install -r requirements.txt
```

### Available Make Commands

```bash
make help         # Show available commands
make setup-dev    # Run setup-dev.sh script
make install-dev  # Install package with dev dependencies
make test         # Run tests with coverage
make build        # Build distribution packages
make lint         # Run code quality checks
make clean        # Clean build artifacts and venv
```

### Running Tests

```bash
make test
```

Or directly with pytest:

```bash
pytest tests/ -v --cov=tagitmd --cov-report=term-missing
```

### Building Distribution

```bash
make build
```

This will create distribution packages in the `dist/` directory.

## Publishing to PyPI

### Prerequisites

1. **Register accounts:**
   - Test PyPI: https://test.pypi.org/account/register/
   - Production PyPI: https://pypi.org/account/register/

2. **Create API tokens:**
   - Test PyPI: https://test.pypi.org/manage/account/#api-tokens
   - Production PyPI: https://pypi.org/manage/account/#api-tokens
   - Set scope to "Entire account" for first upload

3. **Configure credentials:**
   Copy `.pypirc.example` to `~/.pypirc` and add your API tokens:
   ```bash
   cp .pypirc.example ~/.pypirc
   chmod 600 ~/.pypirc
   ```
   Edit `~/.pypirc` and replace the placeholder tokens with your actual tokens.

### Publishing Steps

#### Test on Test PyPI (Recommended First)

```bash
make publish-test
```

Then test installation:
```bash
pip install --index-url https://test.pypi.org/simple/ --no-deps tagitmd
```

#### Publish to Production PyPI

```bash
make publish
```

This will:
1. Clean previous builds
2. Build source and wheel distributions
3. Check distribution files for errors
4. Prompt for confirmation before uploading
5. Upload to PyPI

### Manual Publishing (Alternative)

If you prefer manual control:

```bash
# Build
python3 -m build

# Check distributions
python3 -m twine check dist/*

# Upload to Test PyPI
python3 -m twine upload --repository testpypi dist/*

# Upload to PyPI
python3 -m twine upload dist/*
```

### Version Management

Update version in both files before publishing:
- `pyproject.toml` (line 7)
- `tagitmd/__init__.py` (line 3)

## Requirements

- Python 3.8 or higher
- click >= 8.0
- python-frontmatter >= 1.0.0

## License

MIT
