{"id":13741854,"url":"https://github.com/nilslice/protolock","last_synced_at":"2025-05-16T11:02:43.616Z","repository":{"id":33463689,"uuid":"132845199","full_name":"nilslice/protolock","owner":"nilslice","description":"Protocol Buffer companion tool. Track your .proto files and prevent changes to messages and services which impact API compatibility.","archived":false,"fork":false,"pushed_at":"2024-02-12T21:22:32.000Z","size":541,"stargazers_count":616,"open_issues_count":21,"forks_count":37,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-13T12:17:44.002Z","etag":null,"topics":["cli","golang","productivity","proto-files","protobuf","protoc","protocol-buffers","tools"],"latest_commit_sha":null,"homepage":"https://protolock.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nilslice.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,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-05-10T03:44:29.000Z","updated_at":"2025-05-13T06:51:15.000Z","dependencies_parsed_at":"2024-01-12T08:26:37.952Z","dependency_job_id":"f1348826-f884-4cc5-ba98-cbe3c8d34e2d","html_url":"https://github.com/nilslice/protolock","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilslice%2Fprotolock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilslice%2Fprotolock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilslice%2Fprotolock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nilslice%2Fprotolock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nilslice","download_url":"https://codeload.github.com/nilslice/protolock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518383,"owners_count":22084374,"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","golang","productivity","proto-files","protobuf","protoc","protocol-buffers","tools"],"created_at":"2024-08-03T04:01:03.345Z","updated_at":"2025-05-16T11:02:43.558Z","avatar_url":"https://github.com/nilslice.png","language":"Go","funding_links":[],"categories":["Protocol Buffers","Go"],"sub_categories":["Tools"],"readme":"# protolock\n\nTrack your .proto files and prevent changes to messages and services which impact API compatibility.\n\n![Tests](https://github.com/nilslice/protolock/actions/workflows/test.yml/badge.svg)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://pkg.go.dev/github.com/nilslice/protolock)\n\n## Why\n\nEver _accidentally_ break your API compatibility while you're busy fixing problems? You may have forgotten to reserve the field number of a message or you re-ordered fields after removing a property. Maybe a new team member was not familiar with the backward-compatibility of Protocol Buffers and made an easy mistake.\n\n`protolock` attempts to help prevent this from happening.\n\n## Overview\n\n1. **Initialize** your repository: \n\n        $ protolock init\n        # creates a `proto.lock` file\n\n3. **Add changes** to .proto messages or services, verify no breaking changes made: \n\n        $ protolock status\n        CONFLICT: \"Channel\" is missing ID: 108, which had been reserved [path/to/file.proto]\n        CONFLICT: \"Channel\" is missing ID: 109, which had been reserved [path/to/file.proto]\n\n2. **Commit** a new state of your .protos (rewrites `proto.lock` if no warnings): \n\n        $ protolock commit\n        # optionally provide --force flag to disregard warnings\n\n4. **Integrate** into your protobuf compilation step: \n\n        $ protolock status \u0026\u0026 protoc -I ...\n\nIn all, prevent yourself from compiling your protobufs and generating code if breaking changes have been made.\n\n**Recommended:** commit the output `proto.lock` file into your version control system\n\n## Install\nIf you have [Go](https://golang.org) installed, you can install `protolock` by running:\n\n- Go \u003e= 1.17:\n\n\t```bash\n\tgo install github.com/nilslice/protolock/cmd/protolock@latest\n\t```\n\n- Go \u003c 1.17:\n\n\t```bash\n\tgo get github.com/nilslice/protolock/cmd/protolock\n\t```\n\nOtherwise, download a pre-built binary for Windows, macOS, or Linux from the [latest release](https://github.com/nilslice/protolock/releases/latest) page.\n\n## Usage\n```\nprotolock \u003ccommand\u003e [options]\n\nCommands:\n\t-h, --help, help\tdisplay the usage information for protolock\n\tinit\t\t\tinitialize a proto.lock file from current tree\n\tstatus\t\t\tcheck for breaking changes and report conflicts\n\tcommit\t\t\trewrite proto.lock file with current tree if no conflicts (--force to override)\n\nOptions:\n\t--strict [true]\t\tenable strict mode and enforce all built-in rules\n\t--debug\t[false]\t\tenable debug mode and output debug messages\n\t--ignore \t\tcomma-separated list of filepaths to ignore\n\t--force [false]\t\tforces commit to rewrite proto.lock file and disregards warnings\n\t--plugins \t\tcomma-separated list of executable protolock plugin names\n\t--lockdir [.]\t\tdirectory of proto.lock file\n\t--protoroot [.]\t\troot of directory tree containing proto files\n\t--uptodate [false]\tenforce that proto.lock file is up-to-date with proto files\n```\n\n## Related Projects \u0026 Users\n- [Apache Ozone](https://github.com/apache/ozone)\n- [Fanatics](https://github.com/fanatics)\n- [Salesforce](https://github.com/salesforce/proto-backwards-compat-maven-plugin)\n- [Istio](https://github.com/istio/api)\n- [Lyft](https://github.com/lyft)\n- [Envoy](https://github.com/envoyproxy)\n- [Netflix](https://github.com/Netflix)\n- [VMware](https://github.com/vmware/hamlet)\n- [Storj](https://github.com/storj/storj)\n- [Token.io](https://github.com/tokenio/merchant-proxy)\n- [Openbase](https://github.com/openbase/type)\n- [Zeebee](https://github.com/zeebe-io/zeebe)\n\n## Rules Enforced\n\n#### No Using Reserved Fields\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any message's previously reserved fields or IDs are now being used \nas part of the same message.\n\n#### No Removing Reserved Fields\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any reserved field has been removed. \n\n**Note:** This rule is not enforced when strict mode is disabled. \n\n\n#### No Changing Field IDs\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any field ID number has been changed.\n\n\n#### No Changing Field Types\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any field type has been changed.\n\n\n#### No Changing Field Names\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any message's previous fields have been renamed. \n\n**Note:** This rule is not enforced when strict mode is disabled. \n\n#### No Removing Fields Without Reserve\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any field has been removed without a corresponding reservation of \nthat field name or ID.\n\n#### No Removing RPCs\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any RPCs provided by a Service have been removed. \n\n**Note:** This rule is not enforced when strict mode is disabled. \n\n#### No Changing RPC Signature\nCompares the current vs. updated Protolock definitions and will return a list of \nwarnings if any RPC signature has been changed while using the same name.\n\n---\n\n## Docker \n\n```sh\ndocker pull nilslice/protolock:latest\ndocker run -v $(pwd):/protolock -w /protolock nilslice/protolock init\n```\n\n---\n\n## Plugins\nThe default rules enforced by `protolock` may not cover everything you want to \ndo. If you have custom checks you'd like run on your .proto files, create a \nplugin, and have `protolock` run it and report your warnings. Read the wiki to \nlearn more about [creating and using plugins](https://github.com/nilslice/protolock/wiki/Plugins).\n\n---\n\n## Contributing\nPlease feel free to make pull requests with better support for various rules, \noptimized code and overall tests. Filing an issue when you encounter a bug or\nany unexpected behavior is very much appreciated. \n\nFor current issues, see: [open issues](https://github.com/nilslice/protolock/issues)\n\n---\n\n## Acknowledgement\n\nThank you to Ernest Micklei for his work on the excellent parser heavily relied upon by this tool and many more: [https://github.com/emicklei/proto](https://github.com/emicklei/proto)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilslice%2Fprotolock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnilslice%2Fprotolock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnilslice%2Fprotolock/lists"}