2021-06-21 06:29:11 +00:00
# GLab
2022-10-06 20:15:03 +00:00
![GLab ](docs/assets/glab-logo.png )
2020-08-18 19:06:28 +00:00
2022-05-12 17:58:44 +00:00
[![Go Report Card ](https://goreportcard.com/badge/gitlab.com/gitlab-org/cli )](https://goreportcard.com/report/gitlab.com/gitlab-org/cli)
2022-10-04 19:30:12 +00:00
[![Coverage ](https://gitlab.com/gitlab-org/cli/badges/main/coverage.svg )](https://gitlab.com/gitlab-org/cli/badges/main)
2021-10-07 11:07:19 +00:00
[![Mentioned in Awesome Go ](https://awesome.re/mentioned-badge.svg )](https://github.com/avelino/awesome-go#version-control)
2022-10-17 17:53:10 +00:00
[![Gitpod Ready-to-Code ](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?style=flat&logo=gitpod&logoColor=white )](https://gitpod.io/#https://github.com/quarkusio/quarkus/-/tree/main/)
2021-10-07 10:06:14 +00:00
2021-06-21 06:29:11 +00:00
GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with `git` and your code without switching between windows and browser tabs. Work with issues, merge requests, **watch running pipelines directly from your CLI** among other features.
2020-07-25 19:18:55 +00:00
2022-07-26 21:05:57 +00:00
`glab` is available for repositories hosted on GitLab.com and self-managed GitLab instances. `glab` supports multiple authenticated GitLab instances and automatically detects the authenticated hostname from the remotes available in the working Git directory.
2020-12-20 10:35:53 +00:00
2022-10-06 20:15:03 +00:00
![command example ](docs/assets/command-example.png )
2020-07-27 23:42:37 +00:00
2022-07-26 21:05:57 +00:00
## Table of contents
2020-12-17 11:31:53 +00:00
2022-10-21 14:38:48 +00:00
- [Usage ](#usage )
- [Demo ](#demo )
- [Documentation ](#documentation )
- [Installation ](#installation )
- [Quick Install ](#quick-install )
- [Windows ](#windows )
- [WinGet ](#winget )
- [Scoop ](#scoop )
- [EXE Installer ](#exe-installer )
- [Linux ](#linux )
- [Linuxbrew (Homebrew) ](#linuxbrew-homebrew )
- [Snapcraft ](#snapcraft )
- [Arch Linux ](#arch-linux )
- [KISS Linux ](#kiss-linux )
- [Alpine Linux ](#alpine-linux )
- [Install a pinned version from edge ](#install-a-pinned-version-from-edge )
- [Alpine Linux Docker-way ](#alpine-linux-docker-way )
- [Nix/NixOS ](#nixnixos )
- [MPR (Debian/Ubuntu) ](#mpr-debianubuntu )
- [Prebuilt-MPR ](#prebuilt-mpr )
- [Spack ](#spack )
- [macOS ](#macos )
- [Homebrew ](#homebrew )
- [MacPorts ](#macports )
- [Building From Source ](#building-from-source )
- [Prerequisites ](#prerequisites-for-building-from-source-are )
- [Authentication ](#authentication )
- [Configuration ](#configuration )
- [Environment Variables ](#environment-variables )
- [What about lab ](#what-about-lab )
- [Issues ](#issues )
- [Contributing ](#contributing )
2020-12-17 11:31:53 +00:00
2020-07-25 19:22:14 +00:00
## Usage
2022-07-26 21:05:57 +00:00
```shell
glab < command > < subcommand > [flags]
```
2020-07-25 19:18:55 +00:00
2020-10-28 03:20:59 +00:00
## Demo
2022-07-26 21:05:57 +00:00
2020-10-28 18:49:36 +00:00
[![asciicast ](https://asciinema.org/a/368622.svg )](https://asciinema.org/a/368622)
2021-06-21 06:29:11 +00:00
2021-08-09 03:59:58 +00:00
## Documentation
2022-07-26 21:05:57 +00:00
2021-08-09 03:59:58 +00:00
Read the [documentation ](https://glab.readthedocs.io/ ) for usage instructions.
2020-07-25 19:18:55 +00:00
2020-07-27 07:49:14 +00:00
## Installation
2022-07-26 21:05:57 +00:00
2022-05-12 18:05:16 +00:00
Download a binary suitable for your OS at the [releases page ](https://gitlab.com/gitlab-org/cli/-/releases ).
2020-07-27 07:49:14 +00:00
2022-07-26 21:05:57 +00:00
### Quick install
2021-01-12 23:04:16 +00:00
**Supported Platforms**: Linux and macOS
2022-07-26 21:05:57 +00:00
#### Homebrew quick install
2021-06-21 06:29:11 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-06-21 06:29:11 +00:00
brew install glab
```
Updating (Homebrew):
2022-07-26 21:05:57 +00:00
```shell
2021-06-21 06:29:11 +00:00
brew upgrade glab
```
Alternatively, you can install `glab` by shell script:
2022-07-26 21:05:57 +00:00
```shell
2022-10-21 14:38:48 +00:00
curl -s "https://gitlab.com/gitlab-org/cli/-/raw/main/scripts/install.sh" | sudo sh
2020-08-04 02:50:17 +00:00
```
2022-07-26 21:05:57 +00:00
2021-01-12 23:04:16 +00:00
*Installs into `usr/bin` *
2020-08-04 02:50:17 +00:00
2022-07-26 21:05:57 +00:00
**NOTE**: Take care when running scripts in this fashion. Consider peeking at the install script itself and verify that it works as intended.
2020-09-10 17:00:46 +00:00
2020-07-27 07:49:14 +00:00
### Windows
2022-07-26 21:05:57 +00:00
2020-12-17 11:31:53 +00:00
Available for download via [WinGet ](https://github.com/microsoft/winget-cli ), [scoop ](https://scoop.sh ), or downloadable EXE installer file.
#### WinGet
2022-07-26 21:05:57 +00:00
```shell
2022-02-28 15:04:16 +00:00
winget install glab.glab
2020-12-17 11:31:53 +00:00
```
2021-06-21 06:29:11 +00:00
Updating (WinGet):
2022-07-26 21:05:57 +00:00
```shell
2022-02-28 15:04:16 +00:00
winget install glab.glab
2020-12-17 11:31:53 +00:00
```
2020-07-27 07:49:14 +00:00
2020-08-05 05:11:04 +00:00
#### Scoop
2022-07-26 21:05:57 +00:00
```shell
2020-08-05 05:11:04 +00:00
scoop install glab
```
2021-06-21 06:29:11 +00:00
Updating (Scoop):
2022-07-26 21:05:57 +00:00
```shell
2020-10-15 17:06:49 +00:00
scoop update glab
```
2022-07-26 21:05:57 +00:00
2020-12-17 11:31:53 +00:00
#### EXE Installer
2022-05-12 18:05:16 +00:00
EXE installers are available for download on the [releases page ](https://gitlab.com/gitlab-org/cli/-/releases ).
2020-08-05 05:11:04 +00:00
2020-07-27 07:49:14 +00:00
### Linux
2022-07-26 21:05:57 +00:00
2022-05-12 18:05:16 +00:00
Prebuilt binaries available at the [releases page ](https://gitlab.com/gitlab-org/cli/-/releases ).
2020-07-27 07:49:14 +00:00
2020-08-05 05:11:04 +00:00
#### Linuxbrew (Homebrew)
2022-07-26 21:05:57 +00:00
```shell
2020-11-07 22:39:09 +00:00
brew install glab
2020-08-05 05:11:04 +00:00
```
2021-06-21 06:29:11 +00:00
Updating (Homebrew):
2022-07-26 21:05:57 +00:00
```shell
2020-08-05 05:11:04 +00:00
brew upgrade glab
```
2022-07-26 21:05:57 +00:00
2020-10-15 17:06:49 +00:00
#### Snapcraft
2022-07-26 21:05:57 +00:00
2020-10-15 17:06:49 +00:00
[![Get it from the Snap Store ](https://snapcraft.io/static/images/badges/en/snap-store-black.svg )](https://snapcraft.io/glab)
2020-07-27 07:49:14 +00:00
2022-07-26 21:05:57 +00:00
1. Make sure you have [snap installed on your Linux distribution ](https://snapcraft.io/docs/installing-snapd ).
2020-10-15 17:06:49 +00:00
1. `sudo snap install --edge glab`
2022-10-21 14:38:48 +00:00
1. `sudo snap connect glab:ssh-keys` to grant SSH access
2020-07-27 07:49:14 +00:00
2020-11-14 16:53:54 +00:00
#### Arch Linux
2022-07-26 21:05:57 +00:00
2022-05-12 18:05:16 +00:00
`glab` is available through the [community/glab ](https://archlinux.org/packages/community/x86_64/glab/ ) package or download and install an archive from the [releases page ](https://gitlab.com/gitlab-org/cli/-/releases ). Arch Linux also supports [snap ](https://snapcraft.io/docs/installing-snap-on-arch-linux ).
2022-07-26 21:05:57 +00:00
```shell
2022-01-10 15:00:47 +00:00
pacman -S glab
2020-11-14 16:53:54 +00:00
```
#### KISS Linux
2022-07-26 21:05:57 +00:00
2022-10-21 14:38:48 +00:00
WARNING:
It seems that KISS Linux may no longer be actively maintained, so links to its web domain have been removed from this README.
2021-06-21 06:29:11 +00:00
2022-07-26 21:05:57 +00:00
`glab` is available on the [KISS Linux Community Repository ](https://github.com/kisslinux/community ) as `gitlab-glab` .
If you already have the community repository configured in your `KISS_PATH` you can install `glab` through your terminal.
```shell
2020-11-14 16:53:54 +00:00
kiss b gitlab-glab & & kiss i gitlab-glab
```
2020-07-27 07:49:14 +00:00
2020-12-22 16:31:17 +00:00
#### Alpine Linux
2022-07-26 21:05:57 +00:00
`glab` is available on the [Alpine Community Repository ](https://git.alpinelinux.org/aports/tree/community/glab?h=master ) as `glab` .
2020-12-22 16:31:17 +00:00
2021-01-15 20:08:19 +00:00
##### Install
2022-07-26 21:05:57 +00:00
We use `--no-cache` so an `apk update` is not required.
2021-01-15 20:08:19 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-01-15 20:08:19 +00:00
apk add --no-cache glab
```
2020-12-22 16:31:17 +00:00
##### Install a pinned version from edge
2022-07-26 21:05:57 +00:00
To ensure that by default edge is used to get the latest updates. We need the edge repository in `/etc/apk/repositories` .
2020-12-22 16:31:17 +00:00
Afterwards you can install it with `apk add --no-cache glab@edge`
2022-07-26 21:05:57 +00:00
We use `--no-cache` so an `apk update` is not required.
2020-12-22 16:31:17 +00:00
2022-07-26 21:05:57 +00:00
```shell
2020-12-22 16:31:17 +00:00
echo "@edge http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk add --no-cache glab@edge
```
##### Alpine Linux Docker-way
Use edge directly
2022-07-26 21:05:57 +00:00
```shell
2021-01-15 20:08:19 +00:00
FROM alpine:3.13
2020-12-22 16:31:17 +00:00
RUN apk add --no-cache glab
```
2021-01-15 20:08:19 +00:00
Fetching latest glab version from edge
2020-12-22 16:31:17 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-01-15 20:08:19 +00:00
FROM alpine:3.13
2020-12-22 16:31:17 +00:00
RUN echo "@edge http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
RUN apk add --no-cache glab@edge
```
2022-07-26 21:05:57 +00:00
#### Nix/NixOS
2021-02-03 15:04:40 +00:00
2022-07-26 21:05:57 +00:00
Nix (NixOS) users can install from [nixpkgs ](https://search.nixos.org/packages?channel=unstable&show=glab&from=0&size=30&sort=relevance&query=glab ):
2021-02-03 15:04:40 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-02-03 15:04:40 +00:00
nix-env -iA nixos.glab
```
2022-07-26 21:05:57 +00:00
#### MPR (Debian/Ubuntu)
`glab` is available inside the [makedeb package repository ](https://mpr.makedeb.org/packages/glab ). To install, run the following:
```shell
git clone 'https://mpr.makedeb.org/glab'
cd glab/
makedeb -si
```
##### Prebuilt-MPR
The above method downloads glab from source and builds it before packaging it into a `.deb` package. If you don't want to compile or just want a prebuilt package, you can also install glab from the Prebuilt-MPR.
First [set up the Prebuilt-MPR on your system ](https://docs.makedeb.org/prebuilt-mpr/getting-started/#setting-up-the-repository ), and then run the following:
```shell
sudo apt install glab
```
2022-08-22 13:40:44 +00:00
#### Spack
```shell
spack install glab
```
Updating (Spack):
```shell
spack uninstall glab & & spack install glab
```
2021-02-03 15:24:06 +00:00
### macOS
2020-08-05 05:11:04 +00:00
#### Homebrew
2021-02-03 14:57:27 +00:00
`glab` is available via [Homebrew ](https://formulae.brew.sh/formula/glab )
2022-07-26 21:05:57 +00:00
```shell
2020-11-07 22:39:09 +00:00
brew install glab
2020-08-05 05:11:04 +00:00
```
2022-07-26 21:05:57 +00:00
2020-08-05 05:11:04 +00:00
Updating:
2022-07-26 21:05:57 +00:00
```shell
2020-08-05 05:11:04 +00:00
brew upgrade glab
```
2021-02-03 14:57:27 +00:00
#### MacPorts
`glab` is also available via [MacPorts ](https://ports.macports.org/port/glab/summary )
2022-07-26 21:05:57 +00:00
```shell
2021-02-03 14:57:27 +00:00
sudo port install glab
```
Updating:
2022-07-26 21:05:57 +00:00
```shell
2021-02-03 14:57:27 +00:00
sudo port selfupdate & & sudo port upgrade glab
```
2022-07-26 21:05:57 +00:00
### Building from source
2022-05-12 18:05:16 +00:00
If a supported binary for your OS is not found at the [releases page ](https://gitlab.com/gitlab-org/cli/-/releases ), you can build from source:
2020-07-27 13:44:50 +00:00
2021-06-21 06:29:11 +00:00
#### Prerequisites for building from source
2022-07-26 21:05:57 +00:00
2022-10-21 14:38:48 +00:00
- `make`
- Go 1.13+
2020-10-15 17:06:49 +00:00
1. Verify that you have Go 1.13+ installed
2020-07-27 13:44:50 +00:00
2022-07-26 21:05:57 +00:00
```shell
2020-07-27 13:44:50 +00:00
$ go version
go version go1.14
```
If `go` is not installed, follow instructions on [the Go website ](https://golang.org/doc/install ).
2022-07-26 21:05:57 +00:00
1. Clone this repository
2020-07-27 13:44:50 +00:00
2022-07-26 21:05:57 +00:00
```shell
2022-08-11 21:57:33 +00:00
git clone https://gitlab.com/gitlab-org/cli.git glab
2021-06-21 06:29:11 +00:00
cd glab
2020-07-27 19:02:00 +00:00
```
2022-07-26 21:05:57 +00:00
If you have `$GOPATH/bin` or `$GOBIN` in your `$PATH` , you can just install with `make install` (install glab in `$GOPATH/bin` ) and **skip steps 3 and 4** .
1. Build the project:
```shell
2021-06-21 06:29:11 +00:00
make
2020-07-27 13:44:50 +00:00
```
2022-07-26 21:05:57 +00:00
1. Change PATH to find newly compiled `glab`
2020-07-27 13:44:50 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-06-21 06:29:11 +00:00
export PATH=$PWD/bin:$PATH
2020-07-27 13:44:50 +00:00
```
2022-07-26 21:05:57 +00:00
1. Run `glab version` to confirm that it worked.
2020-07-27 13:44:50 +00:00
2020-11-02 10:42:09 +00:00
## Authentication
2020-07-27 13:44:50 +00:00
2022-07-26 21:05:57 +00:00
Get a GitLab access token at < https: / / gitlab . com / - / profile / personal_access_tokens > or < https: / / gitlab . example . com / - / profile / personal_access_tokens > if self-managed:
2022-10-21 14:38:48 +00:00
- Start interactive setup:
2020-11-02 10:42:09 +00:00
2022-07-26 21:05:57 +00:00
```shell
2021-08-09 03:59:58 +00:00
glab auth login
```
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- Authenticate against `gitlab.com` by reading the token from a file:
2022-07-26 21:05:57 +00:00
```shell
2021-08-09 03:59:58 +00:00
glab auth login --stdin < myaccesstoken.txt
```
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- Authenticate against a self-managed GitLab instance by reading from a file:
2022-07-26 21:05:57 +00:00
```shell
2021-08-09 03:59:58 +00:00
glab auth login --hostname salsa.debian.org --stdin < myaccesstoken.txt
```
2020-10-15 17:06:49 +00:00
2022-10-21 14:38:48 +00:00
- Authenticate with token and hostname. Not recommended for shared environments:
2022-07-26 21:05:57 +00:00
```shell
2021-08-09 03:59:58 +00:00
glab auth login --hostname gitlab.example.org --token xxxxx
```
2020-11-02 10:42:09 +00:00
## Configuration
2022-07-26 21:05:57 +00:00
By default, `glab` follows the XDG Base Directory [Spec ](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html ):
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- The global configuration file is saved at `~/.config/glab-cli` .
- The local configuration file is saved at `.git/glab-cli` in the current working Git directory.
- Advanced workflows may override the location of the global configuration by setting the `GLAB_CONFIG_DIR` environment variable.
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- **To set configuration globally**
2020-11-02 10:42:09 +00:00
2022-07-26 21:05:57 +00:00
```shell
glab config set --global editor vim
```
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- **To set configuration for current directory (must be a Git repository)**
2022-07-26 21:05:57 +00:00
```shell
glab config set editor vim
```
2020-11-02 10:42:09 +00:00
2022-10-21 14:38:48 +00:00
- **To set configuration for a specific host**
2020-11-02 10:42:09 +00:00
2022-07-26 21:05:57 +00:00
Use the `--host` flag to set configuration for a specific host. This configuration is always stored in the global configuration file, with or without the `global` flag.
2020-11-02 10:42:09 +00:00
2022-07-26 21:05:57 +00:00
```shell
glab config set editor vim --host gitlab.example.org
```
2020-09-10 17:00:46 +00:00
2022-07-26 21:05:57 +00:00
## Environment variables
2020-07-27 08:30:07 +00:00
2022-07-26 21:05:57 +00:00
```plaintext
GITLAB_TOKEN: an authentication token for API requests. Setting this avoids being
prompted to authenticate and overrides any previously stored credentials.
Can be set in the config with 'glab config set token xxxxxx'
2020-07-25 19:18:55 +00:00
2022-07-26 21:05:57 +00:00
GITLAB_URI or GITLAB_HOST: specify the url of the gitlab server if self hosted (eg: https://gitlab.example.com). Default is https://gitlab.com.
2020-09-29 06:45:27 +00:00
2022-07-26 21:05:57 +00:00
GITLAB_API_HOST: specify the host where the API endpoint is found. Useful when there are separate [sub]domains or hosts for git and the API endpoint: defaults to the hostname found in the git URL
2021-01-30 21:03:36 +00:00
2022-07-26 21:05:57 +00:00
REMOTE_ALIAS or GIT_REMOTE_URL_VAR: git remote variable or alias that contains the gitlab url.
Can be set in the config with 'glab config set remote_alias origin'
2020-07-25 19:18:55 +00:00
2022-07-26 21:05:57 +00:00
VISUAL, EDITOR (in order of precedence): the editor tool to use for authoring text.
Can be set in the config with 'glab config set editor vim'
2020-08-18 17:16:17 +00:00
2022-07-26 21:05:57 +00:00
BROWSER: the web browser to use for opening links.
Can be set in the config with 'glab config set browser mybrowser'
2020-09-29 06:45:27 +00:00
2022-07-26 21:05:57 +00:00
GLAMOUR_STYLE: environment variable to set your desired markdown renderer style
Available options are (dark|light|notty) or set a custom style
https://github.com/charmbracelet/glamour#styles
2021-06-21 06:29:11 +00:00
2022-07-26 21:05:57 +00:00
NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.
2021-10-27 09:41:35 +00:00
2022-07-26 21:05:57 +00:00
FORCE_HYPERLINKS: set to 1 to force hyperlinks to be output, even when not outputing to a TTY
```
2020-07-25 19:18:55 +00:00
2022-07-26 21:05:57 +00:00
## What about Lab?
2021-01-24 22:44:56 +00:00
2022-09-13 19:30:16 +00:00
Both `glab` and [lab] are open-source tools with the same goal of bringing GitLab to your command line and simplifying the developer workflow.
2021-01-24 22:44:56 +00:00
2022-07-26 21:05:57 +00:00
If you want a tool that's more opinionated and intended to help simplify your GitLab workflows from the command line, then `glab` is for you. However, if you want a tool like [hub] that feels like using Git and allows you to interact with GitLab, consider using [lab].
2021-01-24 22:44:56 +00:00
2021-01-25 01:17:21 +00:00
Some `glab` commands such as `ci view` and `ci trace` were adopted from [lab].
2021-01-24 22:44:56 +00:00
2021-01-25 01:17:21 +00:00
[hub]:https://github.com/github/hub
[lab]:https://github.com/zaquestion/lab
2021-01-24 22:44:56 +00:00
2020-08-28 12:17:25 +00:00
## Issues
2022-07-26 21:05:57 +00:00
2022-05-12 18:05:16 +00:00
If you have an issue: report it on the [issue tracker ](https://gitlab.com/gitlab-org/cli/-/issues )
2020-07-29 00:56:09 +00:00
2020-09-18 00:46:12 +00:00
## Contributing
2022-07-26 21:05:57 +00:00
Feel like contributing? That's awesome! We have a [contributing guide ](https://gitlab.com/gitlab-org/cli/-/blob/main/CONTRIBUTING.md ) and [Code of conduct ](https://gitlab.com/gitlab-org/cli/-/blob/main/CODE_OF_CONDUCT.md ) to help guide you.