# GitAR - Git All Remotes [![Build status](https://github.com/jordilin/gitar/actions/workflows/ci.yml/badge.svg)](https://github.com/jordilin/gitar/actions) [![codecov](https://codecov.io/gh/jordilin/gitar/graph/badge.svg)](https://codecov.io/gh/jordilin/gitar) ![GitAR](./doc/src/images/logo.svg) - [GitAR - Git All Remotes](#gitar---git-all-remotes) - [Installation](#installation) - [Usage](#usage) - [Configuration](#configuration) - [Example open a merge/pull request](#example-open-a-mergepull-request) - [Worth a thousand words](#worth-a-thousand-words) - [Remotes supported](#remotes-supported) - [Operations supported](#operations-supported) - [Merge requests](#merge-requests) - [Pipeline](#pipeline) - [Container registry](#container-registry) - [Project](#project) - [Browse remote using your browser](#browse-remote-using-your-browser) - [Releases](#releases) - [Auth User](#auth-user) - [Trending Repositories](#trending-repositories) - [Logging](#logging) - [Unit tests](#unit-tests) - [Gitar-Amps additional scripts and workflows](#gitar-amps-additional-scripts-and-workflows) - [License](#license) Git multi-remote command line tool. Brings common development operations such as opening a pull request down to the shell. This is an alternative to both Github and Gitlab cli tools. The scope for now is smaller. If you happen to use both Gitlab and Github and wanted to just have one single tool, this can help. Some benefits: * It supports Gitlab and Github. One tool, to rul'em all. * Written in Rust. Fast and Parallelizes operations to gather data locally and remotely. * Common defaults. For example, the title of a pull requests is automatically set to the last commit. Defaults can be overriden when prompted. * Caches API read calls. Common remote calls like gather project data that does not change often (project id, namespace, members), so subsequent calls are very fast. I've only tested on MacOS and Linux. ## Installation You can download the latest release from the releases page and place the binary anywhere in your path. Or you can build from source. Building from source requires the latest stable release of Rust. ```bash cargo build --release ./target/release/gr --help ``` ## Usage **WARNING**: Before using, I'd recommend to familiarize yourself in a test git repository. ### Configuration Place your configuration information in a file called `$HOME/.config/gitar/api`. You'll need to gather a read/write API token from your Gitlab/Github account. You can generate a new configuration file with the following command: ```bash gr init --domain ``` Where `` is the domain of the remote. For example, `gitlab.com` or `github.com`. This will create a new configuration file with some default values. Once created you can append new values for each domain you want. Configuration follows a properties file format. ``` .property=value ``` Example configuration file: ``` # Gitlab.com gitlab.com.api_token= gitlab.com.cache_location=/home//.cache/gr gitlab.com.preferred_assignee_username= gitlab.com.merge_request_description_signature= ## Cache expiration configuration # Expire read merge requests in 5 minutes gitlab.com.cache_api_merge_request_expiration=5m # Expire read project metadata, members of a project in 5 days gitlab.com.cache_api_project_expiration=5d # Pipelines are read often, change often, so expire immediately. gitlab.com.cache_api_pipeline_expiration=0s # Expire read container registry in 5 minutes gitlab.com.cache_api_container_registry_expiration=5m # Cache for reading releases gitlab.com.cache_api_release_expiration=1d ## Max pages configuration # Get up to 10 pages of merge requests when listing gitlab.com.max_pages_api_merge_request=10 # Get up to 5 pages of project metadata, members of a project when listing gitlab.com.max_pages_api_project=5 # Get up to 10 pages of pipelines when listing gitlab.com.max_pages_api_pipeline=10 # Get up to 10 pages of container registry when listing gitlab.com.max_pages_api_container_registry=10 # Get up to 10 pages of releases when listing gitlab.com.max_pages_api_release=10 # Rate limit remaining threshold. Threshold by which the tool will stop # processing requests. Defaults to 10 if not provided. The remote has a counter # that decreases with each request. When we reach this threshold we stop for safety. # When it reaches 0 the remote will throw errors. gitlab.com.rate_limit_remaining_threshold=10 # Github github.com.api_token= github.com.cache_location=/home//.cache/gr github.com.preferred_assignee_username= # github.com.merge_request_description_signature=@my-team # Your company gitlab gitlab.mycompany.com.api_token= ... ``` Cache expiration configuration has three keys: - ``.cache_api_merge_request_expiration: List merge_requests, get a merge request, etc... Any read operation involving merge/pull requests. - ``.cache_api_project_expiration: Get project metadata, members of a project. This information does not change often, so a long expiration is fine. - ``.cache_api_pipeline_expiration: List pipelines, get a pipeline, etc... The values for these keys can accept any number followed by `s` for seconds, `m` for minutes, `h` for hours, `d` for days. For example, `5m` means 5 minutes, `5d` means 5 days, `0s` means immediate expiration. If omitted, the default is immediate expiration, so read operations are always pulled from the remote. When listing merge requests, projects, pipelines, etc... the tool will fetch up to max pages. We can control this per API as follows: - ``.max_pages_api_merge_request: List merge_requests, get a merge request, etc... Any read operation involving merge/pull requests. - ``.max_pages_api_project: Get project metadata, members of a project. - ``.max_pages_api_pipeline: List pipelines, get a pipeline, etc... If omitted, the default global number of pages for all APIs is 10. This is to avoid fetching too much data when the amount of information is large. The default number of results per page for Gitlab is 20 and for Github is 30. ### Example open a merge/pull request Create a configuration file with an API read/write token as explained above. ```bash gr mr create ``` * You are in a feature branch * Prompt for assignee user * Confirmation * Open a merge request ### Worth a thousand words [demo.webm](https://github.com/jordilin/gitar/assets/1031376/83a37d6e-e2eb-4b68-978e-816439b2c122) ## Remotes supported Gitlab and Github. ## Operations supported ### Merge requests In Gitlab they are known as merge requests and in Github as pull requests. | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | Open | ✔ | ✔ | | Approve | ✔ | ✖ | | Merge | ✔ | ✔ | | Get merge request details | ✔ | ✔ | | List merge requests by their state | ✔| ✔ | | Close | ✔ | ✔ | | Create comments on timeline | ✔ | ✔ | | List comments on timeline | ✔ | ✔ | ### Pipeline In Gitlab they are known as pipelines and in Github as actions. | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | List all pipelines | ✔ | ✔ | | List pipeline runners | ✔ | ✖ | | Get pipeline runner details | ✔ | ✖ | | Lint pipeline configuration | ✔ | ✖ | | Get total merged pipeline configuration | ✔ | ✖ | | List project jobs | ✔ | ✖ | ### Container registry | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | List repositories | ✔ | ✖ | | List tags | ✔ | ✖ | | Get image metadata | ✔ | ✖ | ### Project | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | Get | ✔ | ✔ | ### Browse remote using your browser | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | Open git repo in browser | ✔ | ✔ | | Open merge request in browser | ✔ | ✔ | | Open pipeline in browser | ✔ | ✔ | | Open releases in browser | ✔ | ✔ | ### Releases | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | List releases | ✔ | ✔ | | List release assets | ✔ | ✔ | ### Auth User Provided by the `gr my` command provides information about the user that holds the auth token. | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | List assigned merge requests | ✔ | ✔ | | List your projects | ✔ | ✔ | | List your starred projects | ✔ | ✔ | | List your gists | ✖ | ✔ | ### Trending Repositories | Operation | GitLab | GitHub | | --------- | -------------- | -------------- | | List by programming language | ✖ | ✔ | All list operations support the following flags: - `--page` to specify the page to fetch. - `--from-page` and `--to-page` to specify a range of pages to fetch. - `--num-pages` queries how many pages of data are available - `--refresh` to force a refresh of the cache. - `--sort` sorts data by date ascending or descending. Ascending is the default. - `--created-after` and `--created-before` to filter by date if response payloads support `created_at` field. - `--format` to specify the output format. Delimit fields by using a pipe, i.e. ` | ` is the default. ## Logging Logging can be enabled by issuing the `--verbose` or `-v` global flag. By default, INFO logs are enabled and will output to STDERR without interfering with STDOUT in case you want to pipe the output to another command or file. INFO will give just enough information to understand what is happening. You can enable DEBUG logs by setting the `RUST_LOG` environment variable to `debug`. DEBUG is way more verbose. Ex: List all pipelines/actions with logging. ```bash # INFO logs gr --verbose pp list # DEBUG logs RUST_LOG=debug gr --verbose pp list ``` ## Unit tests JSON responses from Gitlab and Github are verified in the contracts folder. Those are used to generate mock responses for unit tests. ```bash cargo test ``` ## Gitar-Amps additional scripts and workflows Gitar-Amps are wrapper scripts that make use of gitar in order to provide additional workflows and use cases. It is a companion project that can be found at ## License This project is licensed under - Source code: MIT license ([LICENSE](LICENSE) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) - GitAR logo: [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)](https://creativecommons.org/licenses/by-nc-sa/4.0/)