Page History

The Skara command-line interface (CLI) tools enables enable a CLI driven workflow where reviews are made either via the mailing lists or in an a web browser using an external Git source code hosting provider's web application. The following CLI tools are currently available as part of project Skara:

• git-jcheck - a backwards compatible Git port of jcheck

• git-webrev - a backwards compatible Git port of webrev

• git-defpath - a backwards compatible Git port of defpath

• git-trees - a backwards compatible Git port of trees

• git-fork - fork a project on an external Git source code hosting provider to your personal space and optionally clone it

• git-sync - sync the personal fork of the project with the current state of the upstream repository
• git-backport - fetch a commit from a remote repository and apply it on top of the current branch

• git-pr - interact with pull requests for a project on an external Git source code hosting provider

• git-info - show OpenJDK information about commits, e.g. issue links, authors, contributors, etc.

• git-token - interact with a Git credential manager for handling personal access tokens

• git-translate - translate between Mercurial and Git hashes

• git-publish - publish a local branch to a remote repository
• git-proxy - proxy all network traffic from a Git command through a HTTP(S) proxy

• git-skara - learn about and update the Skara CLI tool

...

$ git clone https://github.com/openjdk/skara
$ git config --global include.path "$PWD/skara/skara.gitconfig"

The If you are running on an x64 system using Linux, Macos or Windows, the Skara tooling will bootstrap itself the first time you use any of the Skara commands. For other platforms you will need to explicitly provide a JDK 16 or later and run the build directly:

$ JAVA_HOME=/path/to/jdk-16/or/later bash gradlew

To check that To check that everything works run git skara help:

...

Note: if your computer is behind a HTTP(S) proxy, ensure that you have set the HTTPS_PROXY environment variable correctly.

Updating

To update the Skara tooling run git skara update:

$ git skara update

The update command pull eventual updates and rebuild the tooling if necessary. Note: if your computer is behind a HTTP(S) proxy, ensure that you have set the HTTPS_PROXY environment variable correctly.

Personal Access Token

Some of the Skara tools requires a personal access token (PAT) to authenticate against an external Git source code hosting provider's API. A personal access token is a like a password that has limited capabilities, it can only be used to successfully authenticate and perform certain limited actions. The following Skara tools requires a personal access token:

• git-fork
• git-pr
• git-token

Note: if you do not intend to use the above three tools, then there is no need to set up a personal access token and you can skip this section. All the other tools described in the beginning of this document works fine without a personal access token. If you do wish to make use of the above three tools, then please read on.

Configuring a personal access token consists of two steps:

1. Set up a credential manager for securely storing the personal access token locally on your computer
2. Generate the personal access token and store it in the credential manager

The way to carry out the above two steps differs depending on the operating system you use, please follow the instructions below suitable for your operating system.

Windows

Credential Manager

If you installed Git via Git for Windows then you already have a credential manager from Microsoft installed (it is bundled with Git for Windows). If you installed Git via some other mechanism, then you must first install Microsoft's Git Credential Manager for Windows.

Personal Access Token

Note: installing skara more than once can cause issues. If git config --get-all include.path returns more than one line, the skara bootstrap mechanism will get confused. Either make sure to only have one installation, or edit that line to read grep 'skara.gitconfig' | tail -1 assuming the last one is the right one.

For additional ways to install the Skara CLI tooling, see project Skara's README.

Updating

To update the Skara tooling run git skara update:

$ git skara update

The update command pulls eventual updates and rebuild the tooling if necessary. Note: if your computer is behind a HTTP(S) proxy, ensure that you have set the HTTPS_PROXY environment variable correctly.

If you are using system other than Linux, Macos, or Windows x64, you need to provide a JDK 16 or later and run the build directly as described above after using git to update the Skara repository.

If the update command for some reason isn't working or you just want to manually retrace the steps you can each step manually like this:

$ git pull
$ bash gradlew

Personal Access Token

Some of the Skara tools requires a personal access token (PAT) to authenticate against an external Git source code hosting provider's API. A personal access token is a like a password that has limited capabilities, it can only be used to successfully authenticate and perform certain limited actions. The following Skara tools requires a personal access token:

• git-fork
• git-pr
• git-token

Note: if you do not intend to use the above three tools, then there is no need to set up a personal access token and you can skip this section. All the other tools described in the beginning of this document works fine without a personal access token. If you do wish to make use of the above three tools, then please read on.

Configuring a personal access token consists of two steps:

1. Set up a credential manager for securely storing the personal access token locally on your computer
2. Generate the personal access token and store it in the credential manager

The way to carry out the above two steps differs depending on the operating system you use, please follow the instructions below suitable for your operating system.

Windows

Credential Manager

If you installed Git via Git for Windows and have a recent version, then you already have a credential manager from Microsoft installed (it is bundled with Git for Windows, but make sure to pick it during installation). If you installed Git via some other mechanism, then you must first install Microsoft's Git Credential Manager. If you have an older version of Git for Windows and using the deprecated Git Credential Manager for Windows, you may need to configure git to use the credential manager like thisTo generate a a personal access token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your personal access token, store it in the Git Credential Manager for Windows using git token store:

>$ git config token store --global credential.helper manager

Personal Access Token

To generate a a personal access token on GitHub go to https://github.com

...

/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your personal access token, store it in Keychain using git token store:

$ git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

macOS

Credential Manager

macOS already comes with a password manager in the form of Keychain and Git for macOS is configured out of the box to use Keychain as a credential manager, there is no need to configure anything.

...

$ git config configure--global credential.helper store

To generate a personal access token on GitHub go to https://github.com/settings/tokens and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your token, store it in ~/.git-credentials by running git token store:

$ git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

Using

The following sections contains examples on how to use the Skara CLI tools. For more detailed information on how to use a certain tool, pass the -h flag to it, for example git pr -h.

Creating a personal fork

To create a personal fork of an upstream repository, run the command git fork <URL>. For example, to create a personal fork of the jdk repository, run:

$ git fork https://github.com/openjdk/jdk

The command git fork will also clone your personal fork to a local repository on your computer.

Publishing a local branch

Commands

Please see the documentation for each tool on the tool's individual wiki page:

• git-defpath
• git-fork
• git-hg-export
• git-info
• git-jcheck
• git-proxy
• git-publish
• git-skara
• git-sync
• git-token
• git-translate
• git-trees
• git-webrev

Overview

The following sections contains examples on how to use the Skara CLI tools. For more detailed information on how to use a certain tool, see the documentation for that tool.

Creating a personal fork

To create a personal fork of an upstream repository, run the command git fork <URL>. For example, to create a personal fork of the jdk repository, runTo publish a local branch to a remote repository, run the following command:

$ git publish

Creating a pull request

 fork https://github.com/openjdk/jdk

The command git fork will also clone your personal fork to a local repository on your computer.

Publishing a local branch

To publish a local branch to a remote repository, run the following command:

$ git publish

Creating a pull request

To create To create a pull request first create a personal fork, then create a local branch in the local clone of your personal fork. Make changes to a number of files, then create a commit. Publish your local branch and then create a pull request from your published branchlocal clone of your personal fork. Make changes to a number of files, then create a commit. Publish your local branch and then create a pull request from your published branch:

$ git pr create

Notes:

• If you want to run jcheck on your changes before the pull request is created, pass the flag --jcheck

• If you want the local branch to be published automatically, pass the flag --publish

Listing pull requests

To list the open pull requests for a repository, run the command git pr list in a local clone of your personal fork:

$ git pr list

Notes:

• You can filter the listed pull requests by passing additional flags such --assignees=<USERNAMES>, --authors=<USERNAMES>, --labels=<LABELS>
• You can select the columns to show by passing the --columns flag, for example --columns=id,title

Setting properties of a pull request

To set properties of a pull request, run the command git pr set:

$ git pr create

Notes:

• If you want to run jcheck on your changes before the pull request is created, pass the flag --jcheck

• If you want the local branch to be published automatically, pass the flag --publish

Listing pull requests

$ git pr set

Examples:

• To set the title of a pull request, run git pr set --title <TITLE>
• To set the body of a pull request, run git pr set --body <BODY>
• To close a pull request, run git pr set --closed

Integrating a pull request

To integrate a pull request that you have createdTo list the open pull requests for a repository, run the command git pr list in a local clone of your personal forkintegrate:

$ git pr listintegrate

Notes:

• You can filter the listed pull requests by passing additional flags such --assignees=<USERNAMES>, --authors=<USERNAMES>, --labels=<LABELS>
• You can select the columns to show by passing the --columns flag, for example --columns=id,title

Setting properties of a pull request

• If you find yourself typing git pr integrate a lot, you might want to create the alias "integrate":

  Code Block
  language bash
  $ git config --global alias.integrate 'pr integrate'

  You can then just run git integrate to integrate a pull request.

Syncing a personal fork

To sync your personal fork with the upstream repository it was created from, run the command git syncTo set properties of a pull request, run the command git pr set:

$ git pr set

Examples:

• To set the title of a pull request, run git pr set --title <TITLE>
• To set the body of a pull request, run git pr set --body <BODY>
• To close a pull request, run git pr set --closed

Integrating a pull request

To integrate a pull request that you have created, run the command git pr integrate:

$ git pr integrate

Notes:

...

git sync

Notes:

• To sync your personal fork and your local repository, pass the flag --fast-forward
• To sync only a subset of branches, pass the flag --branches=<BRANCHES>

Showing information about a commit

To show additional information about a commit, such as a link to a pull request or JBS issue, run the command git info:

$ git 

...

info

Notes:

• You can then just run git integrate to integrate a pull requestshow a subset of the fields by passing flags, for example --author, --issues, --review, --sponsor etc.