diff --git a/04-branching-basics/README.md b/04-branching-basics/README.md index 0a978f5307846acaec10e4eecd662676520bd213..89a6b6183f9b3547d987e583633c6d5a17143e01 100644 --- a/04-branching-basics/README.md +++ b/04-branching-basics/README.md @@ -21,14 +21,17 @@ Working on the project's content in a specific branch is no different from worki ## Using the CLI to manage branches +### Switching between branches + In the GitLab UI, working in a branch is performed by selecting a branch from the menu (or by creating a new branch). On the command line, switching to another already existing branch is done with the `git checkout` [command](https://git-scm.com/docs/git-checkout) The following screenshot shows how to switch from the current (`main`) branch to the newly created `imaginary-animals` branch:  - ### Note + #### Note Don't forget to do a `git fetch` beforehand to retrieve the information about the branch that was created on the remote repository. +### Creating new branches To create a new branch, use the `git branch` [command](https://git-scm.com/docs/git-branch). This will create a new branch *in the local repository only*. The new branch will be based on the current branch. But the new branch will not be *checked out* (i.e. you will remain on the current branch). You will need to do a `git checkout` to switch to the new branch, as shown in the following screenshot: @@ -41,10 +44,55 @@ shown in the screenshot below: Before creating the second branch, we did a `git checkout` to return to the `imaginary-animals` branch. The `imaginary-animals-lotr` and `imaginary-animals-creepy` branches are two "children" of the same parent branch (`imaginary-animals`). +### Displaying information about branches Using `git branch` without any arguments will display the list of branches in the local repository. Adding the `-a` option will also add what remote branches are currently known to your local repository, as shown in the screenshot below:  +### Merging two branches + +Merging two branches is done by switching to the branch that will hold the result of the merge (the destination branch), and using the `git merge` [command](https://git-scm.com/docs/git-merge)to specify the other branch (the source branch) from which the changes will be merged. The actual merge operation will (try to) apply to the destination branch, all changes made in the successive commits that have been made to the source branch, since the latest merge, or since the most recent branch was created. If the merge operation uses a remote branch that has not been previously checked out, as a source branch, it is necessary to prefix the branch name with the name of the remote repository (i.e `origin/my_source_branch`) otherwise, the name of the source branch is enough. + +### Note + It is recommended to use a `git pull` on the destination branch before attempting the merge to ensure it is in the most recent state. + When the source branch is a local branch, it is also recommended to have done a `git pull`for the same reasons. + +The following screenshot shows the full set of commands that will merge the (source) branch `imaginary-animals-lotr` into the (destination) branch `imaginary-animals` + + + +Sometimes, a merge operation can not be achieved successfully. This happens when there are conflicting changes in the source and destination branch. In this case, the output of the `git merge` command will explicitely mention which files contain conflicts. + +The following screenshot shows what happens when trying to merge the `imaginary-animals-creepy`into the `imaginary-animals` branch, after the previous merge of `imaginary-animals-lotr` into `imaginary-animals`. + + + +In each of the files, the conflicting blocks will be clearly marked as follows: + + - A first line with a set of `<<<<<<<<` characters and the name of the destination branch (or the `HEAD` tag) + - The set of conflicting lines in the destination branch + - A line with a set of `========` characters + - The set of conflicting lines in the source branch + - A line with a set of `>>>>>>>>` characters and the name of the source branch. + +The follwing screenshot shows the conflicting block in the `imaginary.md` file. + + + +The conflict stems from the fact that two entries where added at the end of the file in two separate branches. Git cannot decide which changes to keep in the merge result. + +Solving a conflicts implies: + 1. Editing the file(s) with the conflict(s) to decide what part(s) to keep in the resulting file(s). + 1. For each of these files, use `git add` to include the files in the upcoming commit + 1. Use `git commit` to integrate the files with the now resolved conflict in the destination branch. + +The following screenshot shows the sequence of operations to solve the conflict in `imaginary.md` + + + +Don't forget: in order for the merge result to be integrated into the remote repository, a `git push` is needed. + + diff --git a/04-branching-basics/media/conflict-block.png b/04-branching-basics/media/conflict-block.png new file mode 100644 index 0000000000000000000000000000000000000000..0d007faa24b0f76893ed9ab62fda40618e01e02d Binary files /dev/null and b/04-branching-basics/media/conflict-block.png differ diff --git a/04-branching-basics/media/git-conflict-solved.png b/04-branching-basics/media/git-conflict-solved.png new file mode 100644 index 0000000000000000000000000000000000000000..93d0c2b37aa00770c0654195cecbbf03f3100173 Binary files /dev/null and b/04-branching-basics/media/git-conflict-solved.png differ diff --git a/04-branching-basics/media/git-merge-conflict.png b/04-branching-basics/media/git-merge-conflict.png new file mode 100644 index 0000000000000000000000000000000000000000..ef903d3e9b52621a90ae01e2f6df44e201291c0c Binary files /dev/null and b/04-branching-basics/media/git-merge-conflict.png differ diff --git a/04-branching-basics/media/git-merge.png b/04-branching-basics/media/git-merge.png new file mode 100644 index 0000000000000000000000000000000000000000..09e0de826b755f54c3df15f0cc4e3bfa397789cf Binary files /dev/null and b/04-branching-basics/media/git-merge.png differ