{"id":15566845,"url":"https://github.com/labcatr/labcommitr","last_synced_at":"2026-05-04T18:32:13.755Z","repository":{"id":214327696,"uuid":"726659607","full_name":"labcatr/labcommitr","owner":"labcatr","description":"A typescript technology to standardize commits within a project.","archived":false,"fork":false,"pushed_at":"2024-01-02T23:21:23.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-05T09:48:23.889Z","etag":null,"topics":["cli","git","npm","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/labcatr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-03T01:43:32.000Z","updated_at":"2024-01-02T00:30:30.000Z","dependencies_parsed_at":"2024-01-03T00:09:56.025Z","dependency_job_id":"e0de3bc0-0ba3-45ba-9bd1-62391207defa","html_url":"https://github.com/labcatr/labcommitr","commit_stats":{"total_commits":50,"total_committers":2,"mean_commits":25.0,"dds":"0.020000000000000018","last_synced_commit":"d268a9c855592444859ba150e5390624979f7eaa"},"previous_names":["labcatr/labcommitr"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labcatr%2Flabcommitr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labcatr%2Flabcommitr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labcatr%2Flabcommitr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labcatr%2Flabcommitr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/labcatr","download_url":"https://codeload.github.com/labcatr/labcommitr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246140591,"owners_count":20729802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","git","npm","typescript"],"created_at":"2024-10-02T17:07:29.045Z","updated_at":"2026-05-04T18:32:13.746Z","avatar_url":"https://github.com/labcatr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Labcommitr\n\nA CLI tool for creating standardized Git commits with customizable workflows and presets.\n\n**Labcommitr** is used internally for all @labcatr projects. However, feel free to use it for your own projects!\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n  - [commit](#commit)\n  - [init](#init)\n  - [config](#config)\n  - [preview](#preview)\n  - [revert](#revert)\n- [Configuration](#configuration)\n- [Development \u0026 Testing](#development--testing)\n- [Contributing](#contributing)\n\n## Installation\n\n```bash\nnpm install -g @labcatr/labcommitr\n# or\npnpm add -g @labcatr/labcommitr\n```\n\nAfter installation, use either `labcommitr` or `lab` to run commands.\n\n## Quick Start\n\n1. **Initialize configuration** in your project:\n\n   ```bash\n   lab init\n   ```\n\n2. **Create your first commit**:\n\n   ```bash\n   lab commit\n   ```\n\n3. **Or commit quickly with flags**:\n   ```bash\n   lab commit -t feat -m \"add new feature\"\n   ```\n\n## Commands\n\n### commit\n\nCreate a standardized commit following your project's configuration.\n\n**Usage:**\n\n```bash\nlab commit [options]\nlab c [options]  # Short alias\n```\n\n**Options:**\n\n- `-t, --type \u003ctype\u003e` - Commit type (e.g., `feat`, `fix`, `docs`)\n- `-s, --scope \u003cscope\u003e` - Commit scope (e.g., `api`, `auth`, `ui`)\n- `-m, --message \u003cmessage\u003e` - Commit subject/message\n- `-b, --body \u003cbody\u003e` - Commit body/description\n- `--no-verify` - Bypass Git hooks\n\n**Examples:**\n\n```bash\n# Interactive commit (prompts for missing fields)\nlab commit\n\n# Quick commit with type and message\nlab commit -t feat -m \"add user authentication\"\n\n# Full commit with all fields\nlab commit -t feat -s api -m \"add endpoint\" -b \"Implements REST endpoint for user data\"\n\n# Commit without running Git hooks\nlab commit -t fix -m \"fix bug\" --no-verify\n```\n\n**Notes:**\n\n- Messages and body with spaces must be quoted\n- If all required fields are provided via flags, the commit is created immediately\n- If any required fields are missing, an interactive prompt guides you through completion\n- Supports keyboard shortcuts for faster navigation (see configuration)\n\n---\n\n### init\n\nInitialize Labcommitr configuration in your project. This creates a `.labcommitr.config.yaml` file with your chosen preset and preferences.\n\n**Usage:**\n\n```bash\nlab init [options]\nlab i [options]  # Short alias\n```\n\n**Options:**\n\n- `-f, --force` - Overwrite existing configuration file\n- `--preset \u003ctype\u003e` - Use a specific preset without prompts (options: `conventional`, `gitmoji`, `angular`, `minimal`)\n\n**Examples:**\n\n```bash\n# Interactive setup (recommended)\nlab init\n\n# Overwrite existing configuration\nlab init --force\n\n# Use a specific preset without prompts\nlab init --preset conventional\n```\n\n**What it does:**\n\n- Guides you through selecting a commit convention preset\n- Configures emoji support based on terminal capabilities\n- Sets up auto-staging preferences\n- Generates `.labcommitr.config.yaml` with default shortcuts enabled\n- Validates the generated configuration\n\n**Presets available:**\n\n- **Conventional Commits** - Popular across open-source and personal projects\n- **Angular Convention** - Strict format used by Angular and enterprise teams (includes `perf`, `build`, `ci` types)\n- **Gitmoji** - Emoji-based commits for visual clarity\n- **Minimal** - Start with basics, customize everything yourself later\n\n---\n\n### config\n\nManage and inspect Labcommitr configuration.\n\n**Usage:**\n\n```bash\nlab config \u003csubcommand\u003e\n```\n\n**Subcommands:**\n\n#### show\n\nDisplay the currently loaded configuration with source information.\n\n**Usage:**\n\n```bash\nlab config show [options]\n```\n\n**Options:**\n\n- `-p, --path \u003cpath\u003e` - Start configuration search from a specific directory\n\n**Examples:**\n\n```bash\n# Show current configuration\nlab config show\n\n# Show configuration from a specific directory\nlab config show --path /path/to/project\n```\n\n**What it shows:**\n\n- Configuration source (file path or \"defaults\")\n- Emoji mode status\n- Full configuration in JSON format\n- Helpful warnings if using default configuration\n\n---\n\n### preview\n\nBrowse and inspect commit history interactively without modifying your repository.\n\n**Usage:**\n\n```bash\nlab preview [options]\n```\n\n**Options:**\n\n- `-l, --limit \u003cnumber\u003e` - Maximum commits to fetch (default: 50, max: 100)\n- `-b, --branch \u003cbranch\u003e` - Branch to preview (default: current branch)\n\n**Examples:**\n\n```bash\n# Browse commits on current branch\nlab preview\n\n# Preview commits from a specific branch\nlab preview --branch main\n\n# Limit the number of commits fetched\nlab preview --limit 25\n```\n\n**Interactive Features:**\n\n- **Commit List View:**\n  - Navigate through commits with pagination (10 per page)\n  - Press `0-9` to view details of a specific commit\n  - Press `n` to load next batch (if available)\n  - Press `p` to go to previous batch (if available)\n  - Press `Esc` to exit\n\n- **Commit Detail View:**\n  - View full commit information (hash, author, date, subject, body, files)\n  - Press `b` to toggle body visibility\n  - Press `f` to toggle changed files visibility\n  - Press `d` to view diff\n  - Press `r` to revert this commit (switches to revert command)\n  - Press `←` or `Esc` to go back to list\n  - Press `?` for help\n\n**Notes:**\n\n- Read-only operation - does not modify your repository\n- Fetches commits in batches of 50 (up to 100 total)\n- Works on current branch by default\n- No configuration file required (read-only operation)\n\n---\n\n### revert\n\nRevert a commit using the project's commit workflow. Select a commit interactively and create a revert commit following your project's commit message format.\n\n**Usage:**\n\n```bash\nlab revert [options]\n```\n\n**Options:**\n\n- `-l, --limit \u003cnumber\u003e` - Maximum commits to fetch (default: 50, max: 100)\n- `-b, --branch \u003cbranch\u003e` - Branch to revert from (default: current branch)\n- `--no-edit` - Skip commit message editing (use Git's default revert message)\n- `--continue` - Continue revert after conflict resolution\n- `--abort` - Abort revert in progress\n\n**Examples:**\n\n```bash\n# Interactive revert (uses commit workflow)\nlab revert\n\n# Revert from specific branch\nlab revert --branch main\n\n# Revert without using commit workflow\nlab revert --no-edit\n\n# Continue after resolving conflicts\nlab revert --continue\n\n# Abort a revert in progress\nlab revert --abort\n```\n\n**Interactive Features:**\n\n- **Commit Selection:**\n  - Browse commits with pagination (10 per page)\n  - Press `0-9` to select a commit to revert\n  - Press `n` to load next batch (if available)\n  - Press `p` to go to previous batch (if available)\n  - Press `Esc` to cancel\n\n- **Revert Workflow:**\n  - Shows commit details before reverting\n  - For merge commits, prompts to select parent\n  - Uses your project's commit workflow to create revert commit message\n  - Allows editing commit message before finalizing\n  - Handles conflicts with `--continue` and `--abort` options\n\n**Notes:**\n\n- Requires `.labcommitr.config.yaml` (unless using `--no-edit`)\n- Creates a new commit that undoes the selected commit\n- For merge commits, you'll be prompted to select which parent to revert to\n- If conflicts occur, resolve them manually and use `--continue`\n- Use `--abort` to cancel a revert in progress\n\n---\n\n## Configuration\n\nLabcommitr uses a `.labcommitr.config.yaml` file in your project root. The configuration file supports:\n\n- **Commit types** - Define custom commit types with descriptions\n- **Format options** - Configure scope, body, and emoji requirements\n- **Keyboard shortcuts** - Enable and customize shortcuts for faster navigation\n- **Git integration** - Auto-staging and commit signing preferences\n\nSee [`docs/CONFIG_SCHEMA.md`](docs/CONFIG_SCHEMA.md) for complete configuration documentation.\n\n**Configuration discovery:**\n\n- Searches from current directory up to project root\n- Uses sensible defaults if no configuration found\n- Global configuration support is planned for future releases (see [Planned Features](#planned-features))\n\n---\n\n## Development \u0026 Testing\n\n### Testing Environment\n\n**Note:** Test commands are **development-only** and are not available in the published package. They can only be used when running from the source repository.\n\nFor safe testing of Labcommitr commands without affecting your real repository, use the built-in testing environment:\n\n```bash\n# Set up test environment (default scenario)\npnpm run dev:cli test setup\n\n# Open shell in test environment\npnpm run dev:cli test shell\n\n# Run commands normally (use regular lab command in shell)\nlab commit\nlab preview\nlab revert\n\n# Reset environment for another test\npnpm run dev:cli test reset\n\n# Clean up\npnpm run dev:cli test clean\n```\n\n**Alternative:** You can also use `node dist/index-dev.js` instead of `pnpm run dev:cli`:\n\n```bash\nnode dist/index-dev.js test setup\nnode dist/index-dev.js test shell\n```\n\n**Available Scenarios:**\n\n- `existing-project` - Test adding Labcommitr to existing project\n- `with-changes` - Test commit command with various file states (default)\n- `with-history` - Test preview and revert with rich history\n- `with-merge` - Test revert with merge commits\n- `with-conflicts` - Test conflict resolution workflows\n\n**Examples:**\n\n```bash\n# Set up specific scenario\npnpm run dev:cli test setup --scenario with-history\n\n# List all scenarios\npnpm run dev:cli test list-scenarios\n\n# Check current status\npnpm run dev:cli test status\n```\n\nSee [`TESTING.md`](TESTING.md) for complete testing documentation.\n\n### Publishing (maintainers)\n\nReleases run on push to `main` via `.github/workflows/release.yml` and publish to npm. If publish fails with **E404** or **\"Access token expired or revoked\"**:\n\n1. **npm organization** – The scope `@labcatr` must exist on npm. Create an organization named `labcatr` at [npmjs.com](https://www.npmjs.com/) and ensure the publishing user can publish there.\n2. **GitHub secret** – Create a new npm token (npm Profile → Access Tokens). In the repo set **Settings → Secrets and variables → Actions** → `NPM_AUTH_TOKEN` to that token. If 2FA is required for publishing, use a token type that supports it or temporarily disable 2FA for package publish.\n\n---\n\n## Contributing\n\nContributions are welcome! We appreciate your interest in improving Labcommitr.\n\n### How to Contribute\n\nBefore implementing any changes, please follow this process:\n\n1. **Open an issue** describing your proposed change\n   - Clearly explain what you want to add or modify\n   - Provide **use cases** that demonstrate the value of your change\n   - Include **justification** for why this change would benefit users\n   - Discuss potential implementation approaches if relevant\n\n2. **Wait for review and discussion**\n   - Maintainers will review your proposal\n   - Community feedback is encouraged\n   - We'll discuss whether the change aligns with project goals\n\n3. **Proceed with implementation** (if approved)\n   - Once the proposal is accepted, you can start implementing\n   - Follow the project's development guidelines\n   - Ensure your commits follow the project's commit message format (you can set up using `lab init`)\n\n### Questions?\n\nIf you have questions or need clarification, feel free to open a discussion or issue.\n\n---\n\n## Planned Features\n\n### Global Configuration\n\nSupport for user-level global configuration files to enable consistent commit conventions across multiple projects. This will allow you to:\n\n- Set default commit types and preferences in a single location\n- Apply your preferred commit conventions to all projects automatically\n- Override global settings on a per-project basis when needed\n\n**Use cases:**\n\n- Developers working across multiple repositories who want consistent commit message formats\n- Teams that want to standardize commit conventions organization-wide\n- Personal projects where you want the same commit types everywhere\n\nThe global configuration will be stored in OS-specific locations:\n\n- **macOS/Linux**: `~/.labcommitr.config.yaml` or XDG config directory\n- **Windows**: `%USERPROFILE%\\.labcommitr.config.yaml` or AppData directory\n\nProject-specific configurations will always take precedence over global settings.\n\n---\n\n_Have a feature idea? Open an issue to suggest new features!_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabcatr%2Flabcommitr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flabcatr%2Flabcommitr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabcatr%2Flabcommitr/lists"}