{"id":13847232,"url":"https://github.com/softwareventures/precise-commits","last_synced_at":"2025-07-12T08:31:28.026Z","repository":{"id":40340807,"uuid":"316819105","full_name":"softwareventures/precise-commits","owner":"softwareventures","description":":sparkles: Painlessly apply Prettier by only formatting lines you have modified anyway!","archived":false,"fork":true,"pushed_at":"2025-07-10T18:34:20.000Z","size":5816,"stargazers_count":14,"open_issues_count":12,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-11T00:59:08.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@softwareventures/precise-commits","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"nrwl/precise-commits","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softwareventures.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-11-28T20:46:58.000Z","updated_at":"2025-06-26T18:10:55.000Z","dependencies_parsed_at":"2023-09-25T01:39:35.275Z","dependency_job_id":null,"html_url":"https://github.com/softwareventures/precise-commits","commit_stats":{"total_commits":297,"total_committers":6,"mean_commits":49.5,"dds":0.6195286195286196,"last_synced_commit":"161e9cb878919bc880305a5e04033f65f58d19d8"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/softwareventures/precise-commits","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareventures%2Fprecise-commits","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareventures%2Fprecise-commits/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareventures%2Fprecise-commits/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareventures%2Fprecise-commits/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softwareventures","download_url":"https://codeload.github.com/softwareventures/precise-commits/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareventures%2Fprecise-commits/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264731761,"owners_count":23655279,"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":[],"created_at":"2024-08-04T18:01:13.995Z","updated_at":"2025-07-12T08:31:27.995Z","avatar_url":"https://github.com/softwareventures.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ePrecise Commits\u003c/h1\u003e\n\nThis is a fork of the original project, with bug fixes and support for Windows\nline endings.\n\n\u003cbr\u003e\n\n# Why `precise-commits`?\n\n🔎 It is simply **the most exact and least disruptive way** to add consistent\ncode formatting (by [Prettier](https://prettier.io)) to an existing codebase.\n\n✨ You only **reformat the exact code you have modified anyway** as part of your\nnormal development!\n\n| Tool                | Staged files | Existing commits | PR Build | Arbitrary commands | Precision                       |\n| ------------------- | ------------ | ---------------- | -------- | ------------------ | ------------------------------- |\n| **precise-commits** | ✅           | ✅               | ✅       | ❌                 | **Individual character ranges** |\n| lint-staged         | ✅           | ❌               | ❌       | ✅                 | Entire File                     |\n| pretty-quick        | ✅           | ❌               | ❌       | ❌                 | Entire File                     |\n\n\u003cbr\u003e\n\n# Background\n\nImplementing a new code-style in an existing codebase can be really tricky.\n\n[Prettier](https://prettier.io) is an amazing automated code formatting tool,\nbut that does not mean that introducing it into an existing codebase is trivial.\n\nRegardless of how consistent the existing code-style might be, introducing\n[Prettier](https://prettier.io) will result in larger diffs, which:\n\n1. Increases the complexity and review time burden of PRs on senior team\n   members.\n2. Potentially increases the amount of time it takes to complete a PR in the\n   first place.\n3. Can block concurrent work on the same codebase and/or result in nasty merge\n   conflicts with outstanding feature branches.\n\nOther tools, such as `lint-staged`, made an excellent first step towards\nmitigating the scope of the impact of the points above, by only running linters\nand formatters on files which have changed.\n\nThis is great for small codebases, in which the authors do not mind much that\nthey are polluting the git history of the files they are touching, but **it is\nnot enough**.\n\nIn large and enterprise codebases (particularly those organized as monorepos),\nthe git history of each file is really important.\n\n\u003e If I make a change on line 10 of a 4000 line file, I shouldn't be forced to\n\u003e reformat all 4000s lines (thus making me the last git user to update all of\n\u003e them) as part of my PR.\n\u003e\n\u003e I should just need to reformat line 10.\n\nThis is where `precise-commits` comes in!\n\n\u003cbr\u003e\n\n# Our ideal end-goal...\n\n1. All developers on our team develop using consistent, automated formatting as\n   they write their code. e.g. Running an IDE-based plugin, such as\n   \"vscode-prettier\" with \"format on save\" enabled.\n\n2. Each time they commit, a precommit hook is triggered to _ensure_ that the\n   staged code is formatted consistently.\n\n3. Each time a Pull Request opened on our remote repo, a build is triggered on a\n   CI server, during which the formatting is checked to ensure that all the\n   files touched for that PR were formatted consistently.\n\n\u003cbr\u003e\n\n# How `precise-commits` helps us get there...\n\n1. All developers on our team write their code as they always have.\n\n2. Each time they commit, a precommit hook is triggered which will run\n   `precise-commits` on the code and ensure that **the exact code they already\n   modified** is formatted consistently. Any untouched existing code will not be\n   mutated.\n\n3. Each time a Pull Request opened on our remote repo, a build is triggered on a\n   CI server, during which `precise-commits` runs to ensure that all the\n   **committed lines of code** for that PR was formatted consistently.\n\n\u003cbr\u003e\n\n...and after enough time has passed, **our codebase will be formatted\nconsistently, despite us never having to disrupt our feature-building\nmomentum!**\n\n\u003cbr\u003e\n\n# How it works\n\nThrough analyzing your staged files (or any files modified between two given\ncommit SHAs) `precise-commits` will work out exactly what lines and characters\nwithin those files have actually been changed or added.\n\nIt then uses this information to run [Prettier](https://prettier.io) in a very\nfocused way, allowing it to only reformat what is relevant for your current\nwork, and allowing you to keep your PRs small and explicit!\n\n\u003cbr\u003e\n\n# Installation\n\n`precise-commits` expects `prettier` to be available as a `peerDependency`, so\nyou will need to install this yourself as a `devDependency` of your project.\n\n```sh\nnpm install --save-dev prettier @softwareventures/precise-commits\n```\n\n\u003cbr\u003e\n\n# Usage\n\nIt is intended that you will run `precise-commits` as a CLI, and it will\nautomatically pick up on any of the standard\n[Prettier configuration files](https://prettier.io/docs/en/configuration) you\nmay have in your project, including\n[`.prettierignore`](https://prettier.io/docs/en/ignore#ignoring-files) files.\n\n## 1. Running it manually\n\n1. Add an npm script to your package.json, such as:\n\n```js\n{\n  //...\n  \"scripts\": {\n    \"precise-commits\": \"precise-commits\"\n  }\n  //...\n}\n```\n\n2. Execute the npm script, e.g. for the one above run:\n\n```sh\nnpm run precise-commits\n```\n\n## 2. \"Precommit\" Hook\n\nThe recommended way to run `precise-commits` is as a \"precommit\" hook.\n\nA great tool for setting up the hook is\n[`husky`](https://github.com/typicode/husky). You can install and run it as\nfollows:\n\n```sh\nnpm install --save-dev husky\n```\n\nUpdate the `\"scripts\"` section of your `package.json`:\n\n```js\n{\n  //...\n  \"scripts\": {\n    \"prepare\": \"husky install\",\n    \"pre-commit\": \"npm run precise-commits\"\n  }\n  //...\n}\n```\n\nand create a `.husky/pre-commit` script:\n\n```sh\n#!/bin/sh\n. \"$(dirname \"$0\")/_/husky.sh\"\n\nnpm run pre-commit\n```\n\nIf you use yarn, you might want to add a workaround for the benefit of Windows\nusers, see https://typicode.github.io/husky/#/?id=yarn-on-windows\n\n## 3. As part of a PR build\n\nWhen running a build for your PR, you can run `precise-commits` to ensure that\nthe author's changes are all formatted consistently.\n\nThe key things you need to configure are:\n\n1. The `--check-only` flag for `precise-commits` so that it will error out if it\n   finds any inconsistent formatting\n2. The `--head` and `--base` flags so that `precise-commits` knows what commits\n   it should consider when resolving modified files. Most CI servers will have\n   environment variables you can use to resolve these.\n\nFor example, if your PR is building on [Travis](https://travis-ci.com/), your\nconfig might look like this:\n\n**.travis.yml**\n\n```yaml\n# ... Other config options here ...\ninstall:\n    - yarn install\nscript:\n    - 'if [ \"$TRAVIS_PULL_REQUEST\" != \"false\" ]; then precise-commits\n      --whitelist=\"src/**/*.ts\" --check-only --head=$TRAVIS_PULL_REQUEST_SHA\n      --base=$(git merge-base HEAD $TRAVIS_BRANCH); fi'\n    - yarn test\n    - yarn e2e\n# ... Other config options here ...\n```\n\n\u003cbr\u003e\n\n# CLI Configuration Options\n\nAs was hinted at above, the `precise-commits` CLI supports a few different\nconfiguration options:\n\n- `--whitelist`: **[String, Default: `\"*\"`]**\n    - Whitelist is a glob pattern\n      ([the glob syntax from the glob module is used](https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer)).\n    - It is used to inform what files are considered when resolving modified\n      files (by default all are considered).\n    - Don't forget the quotes around the globs! The quotes make sure that\n      `precise-commits` expands the globs rather than your shell.\n\n\u003cbr\u003e\n\n- `--formatter`: **[String, Default: `\"prettier\"`]**\n    - Currently only prettier is supported\n    - If you are interested in adding support for a different formatter, all you\n      need to do is provide an object which\n      [implements this interface](https://github.com/nrwl/precise-commits/blob/master/src/precise-formatter.ts).\n\n\u003cbr\u003e\n\n- `--check-only`: **[Boolean, Default: `false`]**\n    - Only check the code formatting is consistent with the resolved config\n\n\u003cbr\u003e\n\n- `--base`: **[String, NO DEFAULT]**\n    - Base commit SHA to be used in conjunction with the `--head` flag\n\n\u003cbr\u003e\n\n- `--head`: **[String, CONDITIONAL DEFAULT]**\n    - Later commit SHA (e.g. the `HEAD` of a PR branch) to be used in\n      conjunction with the `--base` flag\n    - NOTE on conditional default: If no value is provided for `--head`, but a\n      value is given for `--base`, it will default to checking \"HEAD\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwareventures%2Fprecise-commits","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftwareventures%2Fprecise-commits","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwareventures%2Fprecise-commits/lists"}