diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..6d9cde2 Binary files /dev/null and b/.DS_Store differ diff --git a/README.md b/README.md index 5565f33..32a7a18 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,15 @@ In this guide we are going to show you how to use Gitlab, however before we get going setting things up it's good to get an understanding of the tool works that powers Gitlab (and Github). So let's dive in and take a look. Where possible I'll include instructions for Github but this guide focuses on using Gitlab primarily. +Have a read about whatis git first, this will help you understand whats happening under the hood, after that you can get going with learning the following operations: + +- [Setting up git on your machine](#getting-setup) +- [Getting code (clone and pull)](./getting-code.md) +- [Sharing code](./commit.md) +- [Learning to branch](./branches.md) +- [Merging branches](./merging.md) + + ## So what is Git? At it's core git is a versioning system to store your code also known as a version control system (VCS). It was developed in 2005 by the creator of the Linux Kernel, Linux Torvalds. @@ -28,13 +37,17 @@ flowchart TD D --> |git pull| A ``` +## Sharing code + +Pushing code to a new repository requires two steps, first you must **commit** the code to your local copy and when you're ready you can **push** that to a remote repository. + +You can read more about how to commit code [here](./commit.md) + ## Sync Issues -When working with other developers you're all going to be cloning and pulling the code from the remote repository to start with and then committing and pushing your changes back. Now this is where it can get messy. Let's say there's a file called **header.html** in your repository and you and another developer change that file and push it back to remote repository. This could end up in what's known as a **merge conflict**. Basically you have both created a different version of the file from the initial clone so what happens now? Which one should be the one stored. Well this is where git is really clever. It accept the first persons commit and push without issues, the second person however will be notified of the conflict and be presented with some options. They will be asked to review the file locally and will be given a version of **header.html** that contains a diff showing both users contributions. You can then resolve this conflict by creating a merged version of both of your files or accept their changes or your changes only. +When working with other developers you're all going to be cloning and pulling the code from the remote repository, if you are all commiting back to the same repository this can lead to something called **merge conflicts**, we'll learn how to deal with them later, but another stratergy is to use branches. -The way to read the merge conflict is to look in the file(s) affected and look for the merge markers ```<<<<<<<```, ```=======``` and ```>>>>>>>``` which highlights the conflicting sections. You decide which changes to keep, remove or modify and save the file. - -A good way to minimise this happening to you is to frequently run ```git pull``` in your working directory to keep up to date with others work, however, whilst this works for small teams larger teams will want to consider something more robust so they don't keep tripping over each other. This is where branches come in! +You can read more about how to merge [here](./merging.md) ## Branches @@ -69,6 +82,8 @@ gitGraph Using branches to manage your code is often referred to as Pull Request Workflow, its great for teams for sharing knowledge and encourages code reviews from other team members, but that can introduce delays in getting your feature merged. +You can read more about how branch [here](./branches.md) + ### HEAD The most recent commit on the currently checked-out branch is indicated by something referred to as the HEAD. This is a pointer to any UID within the repository and when new commits are pushed the HEAD updates. This is how git knows to compare your commit with the HEAD to make a diff on the remote repository. @@ -403,7 +418,7 @@ If you want to sign all your commits from now on, and I recomend this, run the f git config --global commit.gpgsign true ``` -Now you're all ready to get started with learning how to use Git. +Now you're all ready to get started with learning how to use Git and we can start that journey by learning how to **clone** and **pull** code, head [here](./getting-code.md) for more information. --- ##### Follow me for more guides diff --git a/img/commit-hash.png b/img/commit-hash.png new file mode 100644 index 0000000..c45cfac Binary files /dev/null and b/img/commit-hash.png differ diff --git a/merging.md b/merging.md index 0cae8dc..7c06bdf 100644 --- a/merging.md +++ b/merging.md @@ -1,6 +1,23 @@ # Bringing code back together +Merging is a way of getting code from one branch to another, thats to say taking the changes from say the develop branch and bringing those into the main branch for example. You can do merge requests (pull requests on Github) either via the CLI or in the web gui. Lets take a look at the web gui first. + ## Merge Requests in Gitlab +We'll use our example of having a branch called **issue 99**. The first thing we need to do is push some code changes to that branch. This effectively moves the HEAD of the branch (issuse 99) forward from the point it was first split. Git now knows theres changes and it's ahead. You'll get a message like this in Gitlab when you commit the code and view the branch: + +![Message in Gitlab after pushing code to a branch](./img/create-merge.png) + +Go ahead and click create merge request. You'll now see a commit message that shows you whats changing and it'll use data from the commit message to populate the merge request. + +![Merge request ready to go](./img/ready-merge.png) + +Now if you have merge conflicts instead of it saying **Ready to Merge** you'll have a red icon and a merge conflict message. You'll need to resolve the merge conflict before you can continue. If you do fix things make sure you comment it in the activity window. Optionally you can opt to delete the source branch, which effectively closes it off as the code is moved back into the main branch in this case. I personally like doing this as it tidies up the feature branches. + +Now hit the blue merge button and you'll get the notification: + +![Merge COmpleted](./img/merged.png) + +You're all done, the code is merged and if you opted to delete the source branch you'll now be back to having just the one branch in your repository which is called main. ## Merging via the CLI Lets take our example of making a branch for **issue 99**, the diagram below shows the current state of the git repository. @@ -45,10 +62,62 @@ gitGraph merge issue99 commit ``` ---- - ## Merge conflicts +When working with other developers you're all going to be cloning and pulling the code from the remote repository to start with and then committing and pushing your changes back. Now this is where it can get messy. Let's say there's a file called **header.html** in your repository and you and another developer change that file and push it back to remote repository and the same branch (or when branches are merged). This could end up in what's known as a **merge conflict**. + +Basically you have both created a different version of the file from the initial clone so what happens now? + +Which one should be the one stored. Well this is where git is really clever. It accepted the first persons commit and push without issues, the second person however will be notified of the conflict and be presented with some options. They will be asked to review the file locally and will be given a version of **header.html** that contains a diff showing both users contributions. You can then resolve this conflict by creating a merged version of both of your files or accept their changes or your changes only. + +The way to read the merge conflict is to look in the affected file(s) in your code editor and check for the merge markers ```<<<<<<<```, ```=======``` and ```>>>>>>>``` which highlights the conflicting sections. You decide which changes to keep, remove or modify by deleting the lines you don't want including the merge markers and then save the file. + +A good way to minimise this happening to you is to frequently run ```git pull``` in your working directory to keep up to date with others work, however, whilst this works for small teams larger teams will want to consider something more robust so they don't keep tripping over each other. This is where branches come in! + + +## Cherry-picking + +Sometimes you don't want to merge an entire branch but want to select certain features/files to update only, and this is another good reason why to commit regularly as it gives you more granular options. For pulling in the changes you want you can use **cherry-picking**, that is selectively incorporates changes from one branch to another. + +In order to do this you need to get the commit hash, which in Gitlab can be found in the right hand corner of the project code page, or you can use the command ```git log``` + +![Commit hash](./img/commit-hash.png) + +When you identify the commit witht he changes you want run the following commands: + +```bash +git checkout target_branch +git cherry-pick +git push origin target_branch +``` + +Now those changes will be selectively merged into your current working directory. Here we can see that the changes from develop have been merged back into the main branch, and the developer working on the release branch doesn't want to pull fromt he HEAD of main or develop for changes, instead they **cherry-pick** the point in time where the develop branch was merged back into main. Heres a visulalisation of that: + +```mermaid + gitGraph + commit + branch develop + branch release + commit + checkout main + commit + checkout develop + commit id:"B" + checkout main + merge develop id:"MERGE" + commit + commit + checkout release + cherry-pick id:"MERGE" parent:"B" + commit + commit + checkout develop + commit + commit +``` + +--- + ##### Follow me for more guides [](https://awscommunity.social/@Ric) [](https://www.linkedin.com/in/richarvey/)