# How to Validate and Commit Profile Changes Using `distilly_commit`: A Complete Guide

> Learn to validate and commit profile changes with distilly_commit. Use distillycommit validate and distillycommit commit to merge and create Git commits for your titanwings/distilly repository.

- Repository: [Tianyi Zhou/distilly](https://github.com/titanwings/distilly)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Use `distillycommit validate` to check profile JSON/YAML against Distilly's schema before running `distillycommit commit` to merge changes and create a Git commit.**

The `distilly_commit` command-line utility is the primary interface for managing **Person Profile** updates in the Distilly skill framework. Located in the `titanwings/distilly` repository, this tool ensures that every modification to a profile—whether adding a celebrity biography or refining relationship metadata—conforms to strict schema requirements before being persisted to version control.

## Understanding the distilly_commit Architecture

The `distillycommit` CLI is implemented across three key components. The entry point lives in [`bin/distilly.mjs`](https://github.com/titanwings/distilly/blob/dot-skill/bin/distilly.mjs), which parses subcommands and routes them to the Python backend. Validation logic resides in [[`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_schema.py)](https://github.com/titanwings/distilly/blob/dot-skill/tools/skill_schema.py), while the actual merging and Git operations are handled by [[`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py)](https://github.com/titanwings/distilly/blob/dot-skill/tools/skill_writer.py).

When you invoke a commit command, the tool executes a two-phase workflow:

1. **Schema Validation** – The profile is checked against family-specific constraints (colleague, relationship, or celebrity types) to ensure required fields and data types are correct.
2. **Atomic Commit** – After validation passes, [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) merges the delta into the existing skill tree and executes a Git commit with a descriptive message.

## Validating Profile Changes Before Commit

Validation is the mandatory first step in the `distillycommit` workflow. The `validate` subcommand runs the profile through Distilly's schema validator, catching structural errors before they reach the repository.

Run validation using:

```bash
distillycommit validate path/to/profile.json

```

The validator, defined in [`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_schema.py), checks for:

- **Required fields** – Ensures mandatory keys like `name`, `type`, and `attributes` are present.
- **Data type constraints** – Validates that dates, strings, and nested objects match the expected schema.
- **Family-specific rules** – Enforces logic specific to colleague, relationship, or celebrity profile families.

If validation fails, the command exits with a detailed error list including line numbers:

```bash
$ distillycommit validate ./profiles/celeb_karpathy.json
❌ Validation failed: Missing required field "interview_section" at line 42
❌ Validation failed: Invalid data type for "birth_date" at line 15

```

## Committing Validated Profile Changes

Once validation succeeds, use the `commit` subcommand to persist changes. This command accepts a file path and an optional commit message, performing the full write-and-commit sequence atomically.

```bash
distillycommit commit path/to/profile.json \
    --message "Update celeb-profile: Andrej Karpathy – added interview-section"

```

Under the hood, [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) handles the operation by:

- Merging the profile delta into the existing skill directory while preserving previous conclusions.
- Staging the modified files in Git.
- Creating a commit with the provided message (or a default descriptive string).

You can verify the commit was created successfully:

```bash
git log --oneline -1

# Output: a1b2c3d Update celeb-profile: Andrej Karpathy – added interview-section

```

## Interactive Editing with Built-in Validation

For manual edits, use the `edit` subcommand to open `$EDITOR` (falling back to `vi`) and automatically validate upon save:

```bash
distillycommit edit path/to/profile.json \
    --message "Refine relationship profile – added emotional-trigger notes"

```

This workflow:

1. Launches your default editor with the profile file.
2. Upon saving and closing, automatically runs the validation suite from [`skill_schema.py`](https://github.com/titanwings/distilly/blob/main/skill_schema.py).
3. Only proceeds to write and commit if validation passes; otherwise, it reports errors and aborts without creating a commit.

## Advanced Usage Patterns

### Batch Validation

Validate multiple profiles before committing any changes:

```bash
for profile in ./profiles/*.json; do
    distillycommit validate "$profile" || exit 1
done

```

### Custom Commit Messages

If you omit the `--message` flag, `distillycommit` generates a default message based on the profile type and timestamp. For production workflows, always specify explicit messages for audit trails.

### Integration with CI/CD

Add validation to your continuous integration pipeline to prevent malformed profiles from entering the main branch:

```yaml

# .github/workflows/distilly-ci.yml

- name: Validate all profiles
  run: |
    find ./skills -name "*.json" -exec distillycommit validate {} \;

```

## Summary

- **`distillycommit validate`** checks profile JSON/YAML against the schema in [`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_schema.py), reporting line-specific errors before any files are modified.
- **`distillycommit commit`** atomically validates, merges the delta via [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py), stages changes, and creates a Git commit.
- **`distillycommit edit`** provides an interactive workflow that validates upon save, ensuring no invalid profiles reach version control.
- The entry point in `bin/distilly.mjs` routes all subcommands to the Python backend, maintaining consistency across the CLI.

## Frequently Asked Questions

### What happens if validation fails during a commit command?

If validation fails, `distillycommit` reports the specific schema errors (including line numbers) and exits without modifying the skill directory or creating a Git commit. This atomic behavior ensures the repository remains in a consistent state.

### Can I commit changes without validation?

No. The `commit` subcommand automatically invokes the validation logic from [`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_schema.py) before calling [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py). There is no `--skip-validation` flag, as enforcing schema compliance is a core design principle of the Distilly framework.

### Where does `distillycommit` create the Git commit?

The commit is created in the local repository where the Distilly skill directory resides. The command stages only the files modified by [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) and commits them locally. You must run `git push` separately to transfer the commit to a remote repository.

### How do I update multiple profiles at once?

Currently, `distillycommit` operates on individual files. To batch process multiple profiles, use a shell loop to validate all files first, then commit each one individually, or write a wrapper script that iterates over your profiles directory.