Forking How-To

This page contains step-by-step instructions for setting up a forking workflow in Gitlab. For a description of forks, please see the fork overview.

Create Upstream

First, you should create the upstream repository in the code.usgs.gov/ghsc/lhp namespace. Most LHP members will not have permission to edit this namespace, so you should contact a member of the Hazards Development Team (HazDev) and let them know you’d like to create a new repository. You should ensure that you are given a Maintainer role for the repository.

To create a new repository, you will need two names for the repository. Specifically, a title and a slug. The title is a name intended for humans. This should be a short string that describes your repository. It can include capitalization and spaces. For example: My Cool Project.

By contrast, the slug is a name intended for computers - this is used to link to the code on the Gitlab website, as well as to name folders on your computer. The slug should be a lowercase string that does not start with a number. It should not include punctuation, and spaces should be indicated by hyphens. For example: my-cool-project.

Tip

It’s okay if you aren’t sure of the final name of your code, as you can change both the title and slug before releasing the repository. For now, a working name is fine.

Tip

If asked, you should initialize the repository with a README.

Fork Repository

Next, you’ll need to fork the upstream repository into your personal namespace. First, navigate to the page for the upstream repository. The URL will be https://code.usgs.gov/ghsc/lhp/, followed by the repository slug. For example: https://code.usgs.gov/ghsc/lhp/my-cool-project.

This will bring you to the page for the upstream repository. Next, click on the Forks button in the top-right corner:

Show Button Location
An arrow pointing to the "Forks" button on Gitlab.

This will open a page to fork the repository:

Show Example Page
The "Fork Repository" page from Gitlab.

Click on the “Select a namespace” box:

Show Box Location
An arrow points to the namespace box on the fork page.

You will likely see several namespaces, each ending in your username. Click on the namespace that follows the pattern ghsc/users/your-name.

Show Namespace Example
The namespace dropdown menu is open. An arrow points to a namespace labeled "ghsc/lhp/your-name".

Then click the Fork Project button at the bottom of the page:

Show Button Location
An arrow points to the "Fork Project" button on the fork creation page.

Create Development Branch

Once you’ve forked the project, you’ll want to start developing. You should do this in the forked repository, rather than the upstream. Specifically, you should develop on a development branch, which is any branch other than main. To create a development branch, first navigate to the page for the forked repository. This should be https://code.usgs.gov/ghsc/users/ followed by your username, and then the slug. For example: https://code.usgs.gov/ghsc/users/your-name/my-cool-project.

You can use the branch box to see the branch you are currently viewing.

Show Box Location
An arrow points to the branch box on the repository's main page.

If you just forked the repository, then the repository will only have a main branch. We should create a development branch to hold our work. First, click on the + box near the top of the repository:

Show Box Location
An arrow points to the + box on the repository's main page.

Next, select New branch from the drowdown menu:

Show Menu Item
The dropdown menu of the + box is open. An arrow points to the "New branch" option.

This will open a page to create a new branch:

Show Example Page
The new branch page on Gitlab.

You can name the new branch whatever you like. The following examples use development as the branch name, but you might want something more descriptive for your own projects. Type in the name of the new branch, and click the Create branch button at the bottom:

Show Button Location
The new branch page is open and the branch name is filled in as "development". An arrow points to the "Create Branch" button.

This will create the new branch and return you to the main page for the repository. However, the branch box should have changed to indicate you are currently viewing the development branch.

Show Example
An arrow points to the branch box. The box indicates that the development branch is active.

Tip

You can use the branch box to switch between different branches at any time.