Using Git

From Linux User Group at WUR
Jump to: navigation, search

Git is a popular open source version and source code management tool. At Wageningen U&R, we have our own repository management service at https://git.wageningenur.nl , a gitlab instance.

There are several other good introductions on how to use Git for common use (such as here ), but here I will aim to give you the basics for use at Wageningen.

Gitlab

Because of the way Gitlab works, in order to do anything you must first log in once, using your email. This will create an internal user within Gitlab, allowing you to create, browse, and edit projects. If you are trying to collaborate with someone who has not done this step, you will find that you cannot search for their user, as Gitlab doesn't believe it exists.

Next, once you have an account, the next thing you need to do is to add a public key to it. This requires a basic understanding of Using_SSH - if you don't, go there to get acquainted. Go to https://git.wageningenur.nl/profile and then select 'SSH Keys'. If you paste a key with a comment into the Key section, the Title field ought to be automatically completed as this, otherwise you'll have to fill in something unique. Click 'Add Key' and you're done.

Now you can create a new repo. Go back to the start page and hit 'New Project'. The important field is 'Project Name' - this must be unique to your group, and contain no spaces. The Visibility Level is important if you aim to share your code - by default it's private, but you can set it to public. If you create a group (later), all private repos are shared by all members of the group, so you can more carefully control access this way. Hit 'Create Project'.

Git is capable of working in two modes - local, and remote. You can initialise a local repo and only keep it local, tracking only changes locally, or you can elect to push these up to Gitlab. The instructions given to you as you create a new project cover both existing and new local repos. For completeness sake, I've included and annotated them here:

Gitlab examples

Git global setup
git config --global user.name "Dawes, Gwen"
git config --global user.email "gwen.dawes@wur.nl"

You'll be wanting to do this on larger projects. You can also set these fields on each repo individually by omitting --global.

Create a new repository
git clone git@git.wur.nl:dawes001/test-project.git
cd test-project
touch README.md
git add README.md
git commit -m "add README"
git push -u origin master

This is a good method of getting a remote repo connected fast.

Existing folder
cd existing_folder
git init
git remote add origin git@git.wur.nl:dawes001/test-project.git
git add .
git commit
git push -u origin master

This is if you already have some code you want to add. Essentially a copy of below.

Existing Git repository
cd existing_repo
git remote add origin git@git.wur.nl:dawes001/test-project.git
git push -u origin --all
git push -u origin --tags

This example is good if you have a local git repo. You don't have to call your remote repo 'origin', but it's traditional.

Larger Projects

In very large projects with multiple people it's usually a good idea to prevent merges to master without a Merge Request (commonly known as a Pull Request on other platforms). A Pull Request is a formal declaration of code that you want to submit to the project, and it comes from a separate branch that you have created.

To do this, before you submit any changes:

git -b checkout mynewbranch

This will create a new branch called 'mynewbranch' for you to edit. Submit your changes here. Next:

git push -u origin mynewbranch

This will upload your branch to the remote repo and allow it to be tracked. You only need to do this once - subsequent changes can simply be done with:

git push

Once you're happy with the branch and you've uploaded it, you can now go to Merge Request in the project page. Click 'New Merge Request', then you'll be presented with two tabs - the left one is the source, and the right one the destination. Set your branch in the left menu, and the branch you're merging to (often master) on the right. Then click 'Compare Branches'.

This gets you to a page where you can write some verbose comments on the merge origin and reasons. This will be read by the project admin, so try to be clear about your intentions here. One important thing is to assign the admin to 'Assignee' here - this (should!) mail the admin that you've made a request. Be advised that you can continue to update the branch after creating the Request - and this will be included on Merge, so any issues can be fixed before the admin allows your code in.

As an admin, when you get a Merge Request you can see the Discussion, and the related Commits, and finally the associated Changes. Read the changes carefully, and watch for conflicts - this means that git can't work out what the best code is, and you'll have to do something about this manually. You can actually do this in Gitlab if you'd like - but it's usually best to ask the submitter to rebase their code onto a later master, and allow them to deal with the issue. Once you're happy and all Discussions are closed, you can accept the request.

It's usually a good idea to close the branch as well - once it's merged, there ought to be no further updates in parallel to master - instead, make a new branch and use this to develop further in.