GitLab best practice: Difference between revisions

Revision as of 10:35, 26 January 2017

Main Page -> Documentation -> Gitlab best practice

This page is a collection of links to Gitlab documentation and will evolve into some guidelines how to use Gitlab within the project.

Git implements distributed repositories, git itself does not even make an assumption about a master repository. It is however good to have such a master repository and dedicated strategy how to contribute to it.

Terminology

fork: repository copy in a other user space of Gitlab server system
clone: local working copy on a machine
merge:
rebase:

Roles

There are two very different use cases, the

User role: A user wants to download the code, compile it and use it.
Developer role: A developer contributes to the development.

The developer fork

The developer fork is the main feature in Gitlabs/Githubs concept of distributed development, code sharing and code review.

Synchronizing developer fork with main repository

This should be done regularly!

There is unfortunately no simple synchronization feature for forks within Gitlab (from Gitlab Enterprise Edition 8.2 repository mirroring is provided). Synchronization is done in the local clone.

Fetch branch from the master repository

 git fetch https://gitlab.uib.no/pct/wpn.git dev

Rebase local branch
```
 git rebase FETCH_HEAD dev
```
Push to fork
```
 git push origin dev
```

Git commits

Log message format

Handling merge requests

Git allows for two merging strategies, the normal and fast-forward (ff) merging. The normal merging adds a merge commit. This adds additional information, when something has been merged. In contrast to that, the latter requires to synchronize the branch to be merged via rebasing, and does not need a merge commit. This results in a linear commit history (not necessarily in time). Whether to use the one or the other depends on the specific case and taste. Many people prefer a linear commit history. As a rule of thumb one can say:

a relatively small and timely update should be done via ff merge
big developments outside of the main development tree should be merged with merge commits. This allows also for detailed commit messages.

Automatic merges

Gitlab offers the possibility to initiate the merge of a Merge Request (MR) directly from the Web interface. This is very easy and straight forward, however in the Gitlab Community Edition provided by UiB IT, the normal merge procedure is used. As a consequence, every Gitlab Merge Request initiated from the Web interface will include a merge commit.

Fast-forward merges

Fast-forward merges do in contrast to normal git (and Gitlab) merges not produce a separate merge commit. Gitlab Enterprise Edition offers the feature to use fast-forward merges directly from the Gitlab Web interface. UiB IT is providing Gitlab Community Edition, so we do not have this convenient feature right away.

Why fast-forward merges?

Many people consider a linear commit history as an advantage, i.e. not to have merge commits for every merge. A fast-forward merge can be done if only the branch to be merged has additional commits on top of the common commit history. The merge simply means to forward the tip of the target branch.

Workflow

As Gitlab does not provide the functionality, the merge needs to be done outside Gitlab in a local clone from the master repository.

In the workflow below

adjust the project name wpn
adjust the user
adjust the branch name
you can skip the cloning if you have a already a clone

Workflow for merging the dev brach from a user fork

Make a local clone from the master repository

 git clone https://gitlab.uib.no/pct/wpn.git

 git checkout dev

or update an existing clone

 git checkout dev

 git pull --ff-only origin dev

Fetch branch dev from user fork

 git fetch https://gitlab.uib.no/user/wpn.git dev

Merge alias FETCH_HEAD
```
 git merge --ff-only FETCH_HEAD
```
Push the update to the master repository
```
 git push origin dev
```

Gitlab will automatically recognize that the merge request was merged manually and will close it.

@@ Line 39: / Line 39: @@
 == Handling merge requests ==
+Git allows for two merging strategies, the ''normal'' and ''fast-forward (ff)''  merging. The ''normal'' merging adds a ''merge commit''. This adds additional information, when something has been merged. In contrast to that, the latter requires to synchronize the branch to be merged via rebasing, and does not need a merge commit. This results in a linear commit history (not necessarily in time). Whether to use the one or the other depends on the specific case and taste. Many people prefer a linear commit history. As a rule of thumb one can say:
+* a relatively small and timely update should be done via ff merge
+* big developments outside of the main development tree should be merged with merge commits. This allows also for detailed commit messages.
 === Automatic merges ===
-Gitlab offers the possibility to initiate the merge of a Merge Request directly from the Web interface. This is very easy and straight forward, however in the Gitlab Community Edition provided by UiB IT, the ''normal merge'' procedure is used. As a consequence, every Gitlab Merge Request (MR) initiated from the Web interface will include a merge commit.
+Gitlab offers the possibility to initiate the merge of a Merge Request (MR) directly from the Web interface. This is very easy and straight forward, however in the Gitlab Community Edition provided by UiB IT, the ''normal merge'' procedure is used. As a consequence, every Gitlab Merge Request initiated from the Web interface will include a merge commit.
 === Fast-forward merges ===
@@ Line 70: / Line 74: @@
 #:<pre> git merge --ff-only FETCH_HEAD</pre>
 # Push the update to the master repository
-#:<pre> git push origin dev
+#:<pre> git push origin dev</pre>
-Gitlab will automatically recognize that the merge request was merged manually and will close it.
+Gitlab will '''automatically''' recognize that the merge request was merged manually and will '''close''' it.