This repository is part of a tutorial on using JGit, a Java library for working with Git repositories.
The purpose of this repository is to accompany an engineering blog article that explains how to use JGit to interact with GitHub repositories using SSH and configuring the SSH client programmatically.
You can find the engineering blog article here: Working with Git in Java: Part 2 - Using SSH with JGit
The repository and the blog article together serve as a comprehensive guide for developers who want to learn how to get started with using JGit commands to interact with Git repositories in Java and how to authenticate using SSH.
It contains example code that demonstrates how to clone a remote repository and commit and push changes using JGit.
This project is built using:
- Java 21
- Gradle
The repository contains three main Java classes:
Step1_CloningARemoteRepository.java
: This class demonstrates how to clone a remote Git repository using JGit to a local directory on your machine.Step2_AddingAndCommittingChanges.java
: This class demonstrates how to commit changes to a local repository using JGit.Step3_PushingChanges.java
: This class demonstrates how to push changes to a remote repository using JGit.
To use this repository, clone it to your local machine and open it in your preferred IDE.
git clone www.github.com/autotraderuk/jgit-tutorial.git
Before you run the code in this project, you will need to set up an SSH key pair on your machine and either add the public key to your GitHub account or configure the repository you intend to work with to use a Deploy Key.
The jgit-tutorial
project relies on you setting up an environment variable that holds your private SSH key and passphrase (if you have one).
This keeps your key out of the codebase and secure in case you decide to share the project with others or add it to version control.
You can export your SSH key by running the following command in your terminal when you open the project:
export SSH_KEY="<YOUR_PRIVATE_SSH_KEY_HERE>"
If you generated your SSH key with a passphrase, you will also need to export this as an environment variable:
export SSH_KEY_PASSPHRASE="<YOUR_SSH_KEY_PASSPHRASE_HERE>"
For more details on how to do this, you can refer to the blog article (Generating an SSH key pair).
In the Configuration
class, you will need to set the URL of the repository you will be cloning.
This is done by setting the REMOTE_REPOSITORY_SSH_URL
constant.
private static final String REMOTE_REPOSITORY_SSH_URL = "ssh://[email protected]/my-username/my-repo";
If you are using your own repository as the clone target, you need to adapt the URL to match your repository:
ssh://[email protected]/<your-github-name>/<your-repo-name>
In the Configuration
class, you can set the name of the folder where the repository will be cloned.
By default, the repository will be cloned to a directory under your home directory:
~/jgit-cloned-repositories/name-of-cloned-repo
.
You can change this by modifying the LOCAL_REPOSITORY_DIRECTORY_NAME
constant.
To run the Step1_CloningARemoteRepository
class, use the following command at the root of the project:
./gradlew run -PmainClass=uk.co.autotrader.jgit.tutorial.Step1_CloningARemoteRepository
By default, the code will clone the repository to a directory under your home directory: ~/jgit-cloned-repositories/cloned-repo
.
Feel free to change this if you want to clone the repository to a different location in the Configuration
class.
To run the Step2_AddingAndCommittingChanges
class with a commit message,
use the following command at the root of the project:
./gradlew run -PmainClass=uk.co.autotrader.jgit.tutorial.Step2_AddingAndCommittingChanges -PcommitMessage="Your commit message here"
Note: The commitMessage variable is passed in as a system property when running the Step2_AddingAndCommittingChanges code. This allows you to specify a commit message when running the code from the command line.
To run the Step3_PushingChanges
class with a commit message and a branch name,
use the following command at the root of the project:
./gradlew run -PmainClass=uk.co.autotrader.jgit.tutorial.Step3_PushingChanges
This repository is publicly available for educational purposes. Feel free to fork it, submit issues, and create pull requests if you have any improvements or fixes to suggest.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.