{"id":28431747,"url":"https://github.com/block/kotlin-formatter","last_synced_at":"2025-07-24T08:09:18.419Z","repository":{"id":268489738,"uuid":"904444747","full_name":"block/kotlin-formatter","owner":"block","description":"A CLI and IntelliJ IDEA plugin for formatting Kotlin code, leveraging ktfmt for consistent style enforcement.","archived":false,"fork":false,"pushed_at":"2025-07-23T12:12:11.000Z","size":384,"stargazers_count":13,"open_issues_count":4,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-23T14:21:20.606Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/block.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-16T22:45:06.000Z","updated_at":"2025-07-23T12:12:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"66b6cf1d-3205-4aa2-bce3-57719e46f2b6","html_url":"https://github.com/block/kotlin-formatter","commit_stats":null,"previous_names":["block/kotlin-formatter"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/block/kotlin-formatter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fkotlin-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fkotlin-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fkotlin-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fkotlin-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block","download_url":"https://codeload.github.com/block/kotlin-formatter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fkotlin-formatter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266813404,"owners_count":23988544,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-06-05T16:08:16.415Z","updated_at":"2025-07-24T08:09:18.413Z","avatar_url":"https://github.com/block.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kotlin Formatter\n\n[![release](https://img.shields.io/maven-central/v/xyz.block.kotlin-formatter/kotlin-formatter?label=release\u0026color=blue)](https://central.sonatype.com/namespace/xyz.block.kotlin-formatter)\n[![main](https://github.com/block/kotlin-formatter/actions/workflows/push.yml/badge.svg)](https://github.com/block/kotlin-formatter/actions/workflows/push.yml)\n\nThis project provides:\n- **A command-line tool for formatting Kotlin source code files**, implemented as a wrapper around [ktfmt](https://github.com/facebook/ktfmt/tree/main).\n- **An IntelliJ idea plugin** for formatting Kotlin source code files.\n\nIt can be used to automate code formatting, ensuring a **clean and consistent codebase**, while integrating seamlessly into development workflows.\n\n## Why Kotlin Formatter?\nThe main goal of this project is to establish a **single, consistent formatting standard** across CLI, Gradle, and IntelliJ, while integrating smoothly into existing developer workflows.\n\nWhile ktfmt provides a solid foundation, we built Kotlin Formatter to address additional use cases:\n- **Configurable max-width** – When we first explored ktfmt, its CLI [didn’t support configuring max-width](https://github.com/facebook/ktfmt/pull/470). Different projects and repositories have varying formatting standards, and we wanted to support this flexibility. In our case, we use a standard formatting width of 120 characters.\n- **Automated Formatting Support in Git Workflow** – We wanted formatting to be automatically applied before code is committed to prevent formatting drift as early as possible, keeping it closest to the inner development loop.\n- **Format-on-save for IntelliJ** – Format-on-save for IntelliJ – While ktfmt provides IntelliJ integration, our plugin includes format-on-save support in addition to manual formatting, reducing manual steps for developers.\n- **Consistent formatting experience across tools** – We ensure consistency by having CLI, Gradle, and IntelliJ all use the same CLI under the hood, applying the same formatting rules across all workflows.\n\nWe hope these tools will make it easier for teams to maintain a **consistent formatting experience with automated formatting**—whether through Git hook integration or format-on-save—while seamlessly integrating into existing development workflows. 🚀\n\n## CLI Overview\nThe CLI provides the following capabilities:\n- **Format files and directories**: Apply consistent formatting to files, directories, or standard input.\n- **Integrate with Git workflows**:\n  - **Pre-commit**: Format staged files before committing.\n  - **Pre-push**: Check committed files before pushing.\n- **Daemon mode (experimental)**: Run a background process to avoid JVM startup time on repeated formatting calls.\n\n### Usage\n```bash\nkotlin-format [OPTIONS] [FILES...]\n```\n#### Options\n\n| Option                  | Description                                                                                |\n|-------------------------|-------------------------------------------------------------------------------------------|\n| `--set-exit-if-changed` | Exit with a non-zero code if any files needed changes.                                    |\n| `--dry-run`             | Display the changes that would be made without writing them to disk.                     |\n| `--pre-commit`          | Format staged files as part of the pre-commit process. *Mutually exclusive with `--pre-push`.* |\n| `--pre-push`            | Check committed files as part of the pre-push process. *Mutually exclusive with `--pre-commit`.* |\n| `--push-commit=\u003ctext\u003e`  | The SHA of the commit to use for pre-push. Defaults to `HEAD`.                            |\n| `--print-stats`         | Emit performance-related statistics to help diagnose performance issues.                 |\n| `--daemon`              | Run the CLI in daemon mode.                                                               |\n| `--stop-daemon`         | Stop the daemon if it's running.                                                          |\n| `-h, --help`            | Show help message and exit.                                                          |\n\n#### Arguments\n\n| Argument      | Description                                |\n|---------------|--------------------------------------------|\n| `\u003cfiles\u003e`     | Files or directories to format. Use `-` for standard input. |\n\n### ⚡ Daemon Mode (Experimental)\n⚠️ _Warning: daemon mode is experimental and subject to change_ ⚠️\nFormatting via the CLI involves slow Java startup. To avoid this, Kotlin Formatter can be run in daemon mode.\n```bash\nkotlin-format --daemon\n```\n\nIn daemon mode, the CLI starts a server that listens for requests to format files. The port is chosen dynamically, and written to .kotlinformatter/kf.lock in the root of the git dir where kotlin-format is run.\nOnly one daemon will run per git dir. If a daemon is already running, invoking `kotlin-format --daemon` will be a no-op, unless the running daemon is an older version.\n\n.kotlinformatter/kf.lock should be added to your .gitignore.\n\nThe daemon only supports a limited set of formatting options compared to the CLI. To format files using the daemon, send a message containing the options:\n```bash\npre-commit \u003cfiles\u003e\npre-push \u003csha\u003e \u003cfiles\u003e\n```\n\nThe daemon will respond with a status code on the first line of the response, followed by the output of the formatting operation.\n\nA full example of using the daemon might look like this:\n```bash\n# start the daemon in the background\nnohup kotlin-format --daemon \u003e /dev/null 2\u003e\u00261 \u0026\n# read values from lockfile\nline=$(head -n 1 \"$daemon_lock_file\")\nversion=$(echo \"$line\" | cut -d ' ' -f 1)\nport=$(echo \"$line\" | cut -d ' ' -f 2)\n# format files\necho pre-commit file1.kt file2.kt | nc localhost $port\n```\n\nAdditionally, the daemon knows the following commands:\n```bash\nexit # stop the daemon\nstatus # get the status of the daemon\n```\n\nThe daemon will automatically shut down after one hour of inactivity, or if it's been running for more than 24 hours.\nYou can also manually shut down the daemon by sending the `exit` command, or running `kotlin-format --stop-daemon`.\n\n### Installing the CLI\n\nThere are multiple ways to install and use the Kotlin Formatter CLI:\n\n#### 1. Using [Hermit](https://github.com/cashapp/hermit)\nIf you don't have Hermit installed, follow the [Hermit Getting Started Guide](https://cashapp.github.io/hermit/usage/get-started/) to install it first. Once Hermit is installed, you can install the Kotlin Formatter CLI using:\n```bash\n\nhermit install kotlin-format\n```\nOnce installed, you can run the CLI with:\n```bash\nkotlin-format [OPTIONS] [FILES...]\n```\n\n#### 2. Downloading the pre-packaged distribution with a script\nA pre-packaged distribution is available on [Maven Central](https://repo1.maven.org/maven2/xyz/block/kotlin-formatter/kotlin-formatter-dist/) and [GitHub Releases](https://github.com/block/kotlin-formatter/releases)\n```bash\nVERSION=X.Y.Z\ncurl -L -o kotlin-formatter-dist.zip https://github.com/block/kotlin-formatter/releases/download/$VERSION/kotlin-formatter-dist-$VERSION.zip\nunzip kotlin-formatter-dist.zip\ncd kotlin-format-shadow-$VERSION\n```\nOnce downloaded and extracted, you can run the CLI with:\n```bash\n./bin/kotlin-format [OPTIONS] [FILES...]\n```\n    \n#### 3. Downloading the JAR manually\nA fat JAR of the CLI is available on [Maven Central](https://repo1.maven.org/maven2/xyz/block/kotlin-formatter/kotlin-formatter/) and [GitHub Releases](https://github.com/block/kotlin-formatter/releases). Once downloaded, you can run the CLI with:\n```bash\njava -jar path/to/kotlin-formatter-$version-all.jar [OPTIONS] [FILES...]\n```\n\n## IntelliJ IDEA Plugin Overview\nThe plugin enables Kotlin file formatting **on save** or via the **format action**.\n\n### Usage\nTo configure the plugin for a project, create a properties file named kotlin-formatter.properties and place it in the `.idea` directory. The following properties are supported\n- `kotlin-formatter.enabled`: Enable or disable the plugin, disabled by default.\n- `kotlin-formatter.script-path`: Path to the Kotlin Formatter script. The `kotlin-format` library in this project is used if this is not specified.\n\nExample:\n```properties\nkotlin-formatter.enabled=true\nkotlin-formatter.script-path=bin/kotlin-format\n```\n\n🚨 Changes to this configuration require an IDE restart to take effect.\n\n#### Enabling Format-on-Save\nTo enable formatting of files on save, navigate to \"Settings\" \u003e \"Tools\" \u003e Actions on Save\", activate the \"Reformat code\" checkbox, and ensure that the \"Kotlin\" file type is selected.\nMake sure \"Optimize imports\" is NOT enabled for the \"Kotlin\" file type.\n\n### IntelliJ IDEA Plugin Installation\n[Download from JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26482-kotlin-formatter)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fkotlin-formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock%2Fkotlin-formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fkotlin-formatter/lists"}