GitLab and GitHub
This guide is primarily for people who use GIMP in a Linux environment. It assumes some knowledge of Linux, and what a terminal window is.
Git Overview
‘Git’ is a play on the word ‘get’, the name of the version control software used by GitLab and GitHub. The GIMP project is stored and maintained on GitLab, so you need to be able to gain access with an account. Sign up to GitLab and give yourself a user name. GitLab is an open-sourced, web-based repository management tool. A repo, short for repository, is a central location in which data is stored and shared from. A GitLab repo is a collection of files and folders that make up a project, it has branches that are independent versions of the same project. A branch is a copy, a controlled version, of the project at a particular point in its history, and usually has been changed in some way to test changes. GitHub is the same kind version control software, operated as a business, and is focused more on simplicity of use.
Using GitLab
You’ll need to install Git on your system. For instance on Debian-based systems, the terminal command could be:
sudo apt install git
Create Some Keys to Access GitLab Remotely
GitLab requires SSH for secure and authenticated communication between a client, you for instance, and the GitLab server when performing Git operations like cloning, pushing and fetching repositories. Cloning is making a local copy of the repo, fetching is bringing any changes made in the repo to your local copy, pushing is sending changes and content to the server repository. SSH (Secure Shell) is a network protocol that allows secure remote access and uses key pairs to authenticate and establish secure connections. To generate a SSH key pair, you can use the following command in your terminal.
ssh-keygen
Specify a filename, or use the default by pressing enter, and optionally a password. In your home directory, in a hidden folder called .ssh, there are now two id_rsa files, if you went with default names, the .pub one is the public key and you can see it’s contents with a text editor
Log in to your GitLab account and navigate to your user settings. Click on ‘SSH Keys’ in the left-hand navigation menu. Copy and paste your public key into the ‘Key’ field and give the key a relevant title, like ‘PC@Home’. Click the ‘Add Key’ button to save the key. Your SSH public key is now added to your GitLab account and you can use it to authenticate with GitLab repositories. Test if your keys and connection are working with the following terminal command.
$ ssh -T git@ssh.gitlab.gnome.org
Welcome to GitLab, @username!
Fork A Repository
The repository for GIMP is here, with a default branch called ‘master’. The default branch in a GitLab repository is usually the branch that you would create a version from, another branch from. You can’t break anything on the official GIMP repository, only the owners and developers have that worry.
Fork the repository on the GitLab web interface by clicking the ‘Fork’ button, this creates an independent copy of the whole repository in your own GitLab account. You can break this version, but that’s ok. Now, name your version of the GIMP project.
Project name: Your-GitLab-Project-Name
Project URL, select your username as the namespace part
Visibility level: Public
You need somewhere to download it to locally. Make a directory, where you’d like this repository to be located, on your PC. This terminal command will make a folder called ‘YourProject’ in your Linux home folder and change the working directory of the terminal to that folder.
mkdir $HOME/YourProject/
cd $HOME/YourProject/
Clone a Repository
Making a clone of your repository is the next step. Go back to the repository fork page you made, not the original repo, and click the clone button. Copy the text in the Clone with SSH text field and use it after a ‘git clone’ command like in the following example. Use the terminal that is open, and is working in $HOME/YourProject/.
git clone git@ssh.gitlab.gnome.org:username/Your-GitLab-Project-Name.git
This will make a copy of everything in the repository on your local machine. Git will also record where the remote is located for future operations, this reference to an external location, called a ‘remote’, will be named ‘origin’ by Git as a default. Check your remotes with:
$ git remote -v
origin git@ssh.gitlab.gnome.org:username/Your-GitLab-Project-Name.git (fetch)
origin git@ssh.gitlab.gnome.org:username/Your-GitLab-Project-Name.git (push)
Branch a Repository
Now you should have a local copy of a forked repository, you can then create a local branch of that repo. Creating a branch in your local repo is a way to make changes to the downloaded files without affecting the originals, you work on a copied version. First, look at what branches you already have with the ‘git branch’ command:
$ git branch
* master
There is one local branch, which is active. The asterisk next to ‘master’ indicates that it is the currently checked out branch in your repository. A checked out branch is the active version of the local project. To create another local branch, you simply need to specify the name of the new branch, without quotes or any special characters. Let’s use ‘my-branch’
git branch my-branch
Then tell Git to work in the new branch ‘my-branch’ with another command, ‘checkout’.
git checkout my-branch
At this point you are working on a branch of your own downloaded repository. Any files you open and change within the local repo are version controlled, they are unique to the active branch.
Staging and Committing
When you have finished creating, you stage the changes and commit them to your remote project. In Git, staging is the process of preparing changes to be committed. You use the git add command to stage changes, which adds them to the ‘index’ or ‘staging area’. Once your changes are staged, you can commit them using the git commit command, which creates a kind of package for the changes and records a commit message that describes the changes made in it.
Here’s the command to add all of your changes.
git add .
The . (period) specifies the current directory as the path to add, so this command will add all changes in the current directory and its subdirectories. Now we can commit the added changes with a message.
git commit -m 'added new content or made some changes'
Pushing to Your Repository
Finally we push the commit back to your project on the GitLab server. It pushes, or uploads, the staged changes from your local repository branch to a remote repository, typically the repository you cloned your local repository from, usually called ‘origin’.
git push origin my-branch
When you push a new branch to a remote repository using the git push command, Git will create a new branch in the remote repository with the same name as the local branch you are pushing. Your branch has now got two versions, one remotely stored on GitLab and one stored locally.
Submit a Merge Request (a Pull Request on Github)
Merge requests are the way to make a change to the GIMP application. Return to the GitLab webpage for your fork, in the interface submit a merge request, a ‘MR’. The usual target branch is ‘GNOME/gimp: ‘master’’. The merge request will be responded to by a member of the GIMP team, with helpful comments on how it can be refined to best suit the needs of the project. Each MR, needs to be carefully examined by an experienced GIMP developer. This makes GIMP a safe and trustworthy application. Features that seem perfect to one person may be undesirable to another.
Make Some Changes
Let’s imagine there are some minor changes to make to the MR after you pushed it to your Gitlab remote repo. You make those changes locally on your branch, remembering to checkout the branch first. In your local repo directory open a terminal:
git checkout my-branch
Then make the necessary changes to the files. Stage the changes you made with git ‘add’. Next amend the previous commit, ‘amend’ is used to modify the most recent commit in the repository.
git add .
git commit --amend
A text editor will pop up asking if you want to change the commit message. This can be avoided with the ‘–no-edit’ flag. Now you can push the changes back to your fork on GitLab, which will automatically pick up the changes to the commit you have amended.
git push --force origin my-branch
If your merge request is accepted by team GIMP, it is merged with the main GIMP repository, into the master branch. Congratulations, please maintain the feature and improve it for ever.
Updating Your Fork From Upstream
Time passes, days, weeks months or years…
…at some point you may return to work again on this repo and you’ll need to update your GitLab fork with the latest upstream content. ‘Upstream’, like it sounds, means the repository the current one was cloned or forked from. Many changes may have occurred upstream.
To get those changes we add the upstream as a remote. Open a terminal in your repo directory:
git remote add upstream git@ssh.gitlab.gnome.org:GNOME/gimp.git
The @ address comes from GitLab and the ‘clone’ button of the repository. https://gitlab.gnome.org
Now you have a remote pointing at the upstream repository named ‘upstream’. We need to fetch any content from upstream and then merge it into the local clone of your fork, which has a branch called ‘my-branch’.
Set your active branch:
git checkout my-branch
Then fetch content from the upstream master branch and merge, or ‘rebase’ with your local checked out branch:
git fetch upstream
git rebase upstream/master
There might be cases where ‘conflicts’ arise, someone has changed the same file that you changed. If Git encounters conflicts while rebasing, it will pause and ask you to resolve those conflicts manually.
This will update your local active branch with the latest master branch in the upstream repository. Now you can stage the changes with add and commit:
git add .
git commit -m 'Update your fork with upstream changes'
Push the locally updated branch to your GitLab fork:
git push origin my-branch
That’s it, you’ve now updated your fork with the latest changes from the upstream repository. It’s also good practice to rebase your version of the master branch from upstream on a regular basis. Like this:
git checkout master
git fetch upstream
git rebase upstream/master
git push origin master
Git Tips
Find out what branch you are in, and what the state of that branch is. For example, what files have been modified?
git status
Store changes before switching branches, if it’s not stashed or not committed it is lost.
git stash
Return to the branch, checking it out, and restore your work in progress.
git stash pop
Make your master branch exactly the same as the GIMP master. Warning, this will remove local files and changes in your master branch.
git checkout master
git fetch upstream
git reset --hard upstream/master
git clean -df
Change a local repo remote to point to a different remote.
git remote -v
git remote remove origin
git remote add origin git@ssh.gitlab.gnome.org:your-stuff/your-project.git
Force a delete of a local branch.
git branch -D your-local-branch
‘git help -a’ and ‘git help -g’ list available subcommands and some concept guides. See ‘git help
git help workflows