{"id":14008242,"url":"https://github.com/ajoberstar/grgit","last_synced_at":"2025-05-15T02:02:51.160Z","repository":{"id":10174123,"uuid":"12258882","full_name":"ajoberstar/grgit","owner":"ajoberstar","description":"The Groovy way to use Git.","archived":false,"fork":false,"pushed_at":"2024-10-05T19:24:49.000Z","size":1795,"stargazers_count":517,"open_issues_count":0,"forks_count":93,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-10T11:08:47.863Z","etag":null,"topics":["git","groovy","jgit"],"latest_commit_sha":null,"homepage":"https://ajoberstar.org/grgit/main/index.html","language":"Groovy","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/ajoberstar.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,"publiccode":null,"codemeta":null}},"created_at":"2013-08-21T01:56:27.000Z","updated_at":"2024-12-09T21:50:48.000Z","dependencies_parsed_at":"2022-08-07T05:15:32.811Z","dependency_job_id":"b7d5402e-eb4a-417e-a35d-fdd8c997ed67","html_url":"https://github.com/ajoberstar/grgit","commit_stats":{"total_commits":523,"total_committers":39,"mean_commits":13.41025641025641,"dds":0.2906309751434034,"last_synced_commit":"9f2f8d04dedf7f56527a6531ffe1a0c2af8cdc53"},"previous_names":[],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoberstar%2Fgrgit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoberstar%2Fgrgit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoberstar%2Fgrgit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoberstar%2Fgrgit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajoberstar","download_url":"https://codeload.github.com/ajoberstar/grgit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281422,"owners_count":21077423,"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":["git","groovy","jgit"],"created_at":"2024-08-10T11:01:29.983Z","updated_at":"2025-04-10T19:34:25.001Z","avatar_url":"https://github.com/ajoberstar.png","language":"Groovy","readme":"# grgit\n\n![CI](https://github.com/ajoberstar/grgit/workflows/CI/badge.svg)\n\n\u003e [!NOTE]\n\u003e As of 5.0.0, grgit is only published to Maven Central\n\n## Project Status\n\nMy opinion is that grgit no longer serves a useful purpose in the Gradle ecosystem, given the evolution towards Kotlin DSL and the stronger preference to move build logic into plugins.\n\nHowever, I understand the backwards compatibility need, so I'm not immediately stopping maintenance. I do consider the plugin **feature frozen**, and don't anticipate doing any work outside of updating dependencies and limited work to maintain compatibility with new versions of Gradle.\n\nFor my own sake, I've already decoupled reckon (which I don't plan to deprecate/archive) from grgit. I anticipate doing the same with gradle-git-publish, but I haven't had the time yet.\n\nFor more background on this see my [Don't commit to grgit](https://andrewoberstar.com/posts/2024-04-02-dont-commit-to-grgit/) blog post.\n\n## Getting Help\n\n\u003e [!IMPORTANT]\n\u003e I consider this plugin feature frozen. Requests for new features _will be closed_.\n\nIf updating grgit versions or Gradle versions causes a bug in **existing grgit behavior** in your build, feel free to open an issue.\n\n## Why do you care?\n\n[JGit](https://eclipse.org/jgit/) provides a powerful Java API for interacting with Git repositories. However,\nin a Groovy context it feels very cumbersome, making it harder to express the operations you want to perform\nwithout being surrounded by a lot of cruft.\n\n\u003e [!CAUTION]\n\u003e See the \"Project Status\" section above and consider if you really need grgit's functionality. I strongly advise against using it in new Groovy projects or Gradle builds.\n\n## What is it?\n\nGrgit is a wrapper over JGit that provides a fluent API for interacting with Git repositories in Groovy-based\ntooling.\n\n\"porcelain\" commands are the primary scope of what is included. Features that require\nmore user interaction (such as resolving merge conflicts) are intentionally excluded.\n\nIt also provides a Gradle plugin to easily get a Grgit instance for the build's repository.\n\n## Documentation\n\n\u003e [!NOTE]\n\u003e grgit is only available from Maven Central\n\n- [Documentation Site](https://ajoberstar.org/grgit/main/index.html)\n- [Release Notes](https://github.com/ajoberstar/grgit/releases)\n\n\u003e [!IMPORTANT]\n\u003e grgit **is not compatible** with Gradle's configuration cache and is **out of scope** for future work on grgit.\n\n## Simple Usage in Gradle\n\n\u003e [!NOTE]\n\u003e `org.ajoberstar.grgit` has poor compatibility with Kotlin scripts. See #361 for an example. \n\nApply the `org.ajoberstar.grgit` plugin in any project that needs to access a `Grgit` instance.\n\n\u003e [!NOTE]\n\u003e This plugin eagerly opens a Grgit instance, which may not be needed depending on the tasks you want to run. If this is not desired, see the next section.\n\n``` groovy\nplugins {\n  id 'org.ajoberstar.grgit' version '\u003cversion\u003e'\n}\n\n// adds a grgit property to the project (will silently be null if there's no git repo)\ntasks.register(\"describe\") {\n  doFirst {\n    println grgit.describe()\n  }\n}\n```\n\n## More Performant Usage in Gradle\n\nApply the `org.ajoberstar.grgit.service` plugin instead of `org.ajoberstar.grgit` to avoid eagerly resolving the `Grgit` instance. This works best with custom tasks that accept a `Property\u003cGrgitService\u003e`.\n\nThis approach ensures you only open a `Grgit` instance when a task is run that uses it.\n\n``` groovy\nimport org.ajoberstar.grgit.gradle.GrgitService\n\nplugins {\n  id 'org.ajoberstar.grgit.service' version '\u003cversion\u003e'\n}\n\ntasks.register(\"describe\", DescribeTask, grgitService.service)\n\nclass DescribeTask extends DefaultTask {\n    private final Provider\u003cGrgitService\u003e service\n\n    @Inject\n    DescribeTask(Provider\u003cGrgitService\u003e service) {\n        this.service = service\n        usesService(service)\n    }\n\n    @TaskAction\n    void execute() {\n        println service.get().grgit.describe()\n    }\n}\n```\n\n### Custom Gradle Plugins\n\nIf you are writing a custom Gradle plugin, you'll want to use one or both of the following approaches:\n\n- If you need a `Grgit` instance representing the repository the project is in, use `org.ajoberstar.grgit.service` and use the `GrgitServiceExtension` to access the shared `GrgitService`. Wire this into any tasks or whatever needs to use the service via `Property\u003cGrgitService\u003e` for full lazy evaluation benefits.\n- If you need a `Grgit` instance that's separate from the project's repository, declare your own `GrgitService` naming it something _not_ prefixed with `grgit*`.\n\n  ``` groovy\n  Provider\u003cGrgitService\u003e serviceProvider = project.getGradle().getSharedServices().registerIfAbsent(\"grgit\", GrgitService.class, spec -\u003e {\n      // use getCurrentDirectory() if you need to search upwards from the provided directory\n      spec.getParameters().getCurrentDirectory().set(project.getLayout().getProjectDirectory());\n      // or use getDirectory() if you want to specify a specific directory and not search\n      spec.getParameters().getDirectory().set(project.getLayout().getBuildDirectory().dir(\"my-custom-repo\"));\n      // generally, this should be false, unless you're using getDirectory() choose to have the repo initialized if the directory does not exist\n      spec.getParameters().getInitIfNotExists().set(false);\n      // I recommend setting this to 1 unless you know better, this will avoid multiple parallel tasks editing the repo at the same time\n      // This should be coupled with tasks that use the service calling \"usesService()\" to register their usage of the service\n      spec.getMaxParallelUsages().set(1);\n    });\n  ```\n\n## Finding versions of grgit\n\n### Newest versions are on Maven Central\n\nAs of 4.1.1, grgit is published to Maven Central and the Gradle Plugin Portal.\n\nAs of 5.0.0, this project is no longer directly published to the Gradle Plugin Portal, but since the portal proxies Maven Central you can still access it through the portal. The only side effect is that [the portal](https://plugins.gradle.org/plugin/org.ajoberstar.grgit) will no longer list the latest version. Use this repo or [search.maven.org](https://search.maven.org/search?q=g:org.ajoberstar.grgit) to find the latest version.\n\n### Old versions from Bintray/JCenter\n\nThis project was previously uploaded to JCenter, which was deprecated in 2021.\n\nIn the event that JCenter is unavailable and acess to past versions (4.1.0 and earlier) is needed, I've made a Maven repo available in [bintray-backup](https://github.com/ajoberstar/bintray-backup). Add the following to your repositories to use it.\n\n```groovy\nmaven {\n  name = 'ajoberstar-backup'\n  url = 'https://ajoberstar.org/bintray-backup/'\n}\n```\n\nMade possible by [lacasseio/bintray-helper](https://github.com/lacasseio/bintray-helper) in case you have a similar need to pull your old Bintray artifacts.\n\n## Acknowledgements\n\nThanks to [everyone](https://github.com/ajoberstar/grgit/graphs/contributors) who has contributed to the library.\n","funding_links":[],"categories":["Groovy"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajoberstar%2Fgrgit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajoberstar%2Fgrgit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajoberstar%2Fgrgit/lists"}