Introduction to Git

This guide aims to introduce you to the operation, configuration, and use of the Git service integrated into Tuleap. We will focus on the features offered by Tuleap for managing your source code repositories.

In Tuleap, the Git service natively integrates with project tracking tools. This integration allows for a seamless link between commits, branches, pull requests, and the platform's artifacts.

This complete traceability allows each team member to understand the context of a code modification, easily navigate from a task to a commit, and ensure that every change is justified and validated.

Practical Info

It is also possible to integrate Tuleap with repositories hosted on an external GitLab instance to benefit from complete traceability between your Tuleap artifacts and your code. This integration allows you to combine Tuleap's project management with GitLab's CI/CD features. This functionality is described in more detail on the full documentation page for the Git service.

Warning

To use this service, you must activate the “Git” service in your Tuleap instance administration and in your project administration.

Prerequisites: Getting familiar with Git

Learning Git Concepts

Before using the tools, understanding how Git works is essential.

The "Pro Git" book, written by Scott Chacon and Ben Straub and available online for free, is the most comprehensive resource for learning how Git works, from the basics to the most advanced concepts like branches and merges.

Choosing a Git client

A Git client is the software you will install on your computer to communicate with the repository hosted on Tuleap.

• Graphical Clients (GUI): there are many options for Windows, macOS, and Linux. Tools like Sourcetree, GitKraken, or GitHub Desktop offer a visual interface to simplify Git operations.

• Command Line (git client): the most direct and universal method. The client is installed via your distribution's package manager or by downloading it from the official Git website.

• Also, most modern Integrated Development Environments (IDEs) include support for Git, either natively or through extensions. Be sure to check the installation options for your favorite IDE.

Create a new Git repository

The first step to using the service is to create a repository that will host your code.

Creating new repositories is a simple operation that can be performed by the project administrator or the Git service administrator.

1. Go to the Git service in your Tuleap project.

2. Click on the button to create a new repository.

3. Enter the desired name for the repository, then click “Add repository”.

Once created, the repositories appear in the project repositories list. You can create as many repositories as you want; they are all managed locally by the Tuleap platform.

Explore a repository

By selecting a repository from the list, you can access its main page and view all related information.

On this page, you will find several key pieces of information:

• The repository name: this is displayed at the top of the page.

• The files: this section contains all files associated with the repository. Each file can be downloaded or viewed as needed by the user.

• The number of pull requests: a counter indicates the number of pull requests pending review.

Navigating the commit history

By default, the information area displays the commit log (shortlog) of the main branch (usually master or main).

You can easily select the branch you want to inspect to display its specific history.

By clicking on the "Commits" tab, you will access a more detailed view of the complete history of the selected branch.

To get all the information related to a specific change, just click on a commit in the list. You will then be able to view:

• The author and the committer.

• The unique identifiers (commit, tree, parent).

• The detailed commit message.

• Any references to Tuleap artifacts.

• The list of affected files.

The code changes can be viewed as a "diff," either globally or file by file.

Clone the repository

To start working on the code, you must first create a local copy of the repository hosted on Tuleap.

To do this, you can clone the repository using either the HTTPS protocol or the SSH protocol. Your choice will determine the required authentication method.

• Via HTTPS: this method requires a "Personal Access Token" to authenticate you. You must first generate this token from your user profile preferences in Tuleap. During the cloning operation, you will need to use your username and the personal access token as the password.

• Via SSH: using the SSH protocol is often more convenient and faster. for this method, it is essential to have previously configured a public SSH key in your Tuleap user profile. Once your public key is added to your account, you can clone the repository without having to enter your credentials for each operation.

Managing code review with Pull Requests

Pull Requests (PRs) are the central tool in Tuleap for code review. They allow your team to discuss proposed changes before merging them into a main branch.

This feature will only be available if the “Pull request” plugin is installed and activated

Create a Pull Request

1. From the repository page, click the “Create pull request” button.

2. Select the source branch (the one containing your changes) and the destination branch (the one you want to merge into).

Once created, the PR appears in the list of pending Pull Requests.

Reviewing the code

Click on a PR to access its details page. There you will find:

• The requester of the PR.

• A summary of the changes.

• A space for general comments.

Project members can discuss the changes and navigate to the "Changes" tab to see all modifications. Tuleap allows you to comment on a specific line of code by simply clicking on its number, thus facilitating precise and contextualized feedback.

Finalizing a Pull Request

At the end of the review, two main options are available to you:

• Abandon the PR if the changes are not accepted.

• Merge the PR to merge the changes into the target branch.