ric/git-guide
1
0
Fork 0
mirror of https://gitlab.com/ric_harvey/git-guide.git synced 2024-11-23 20:24:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

first spelling fix

Browse source
This commit is contained in:
Ric Harvey 2024-05-02 13:23:23 +01:00
parent 679b37d629
commit 4f87315c65
Signed by: ric
GPG key ID: CD63CE502B962F16
2 changed files with 19 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
README.md
View file

@ -1,12 +1,12 @@
# Git Guide
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 primerially.
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.
## 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.
The system also allows developers to work on code simultaniously as each developer *checks out* a local copy of the *repository* to make their changes on. These changes can then ve *commited* back to the central repository and other developers can *pull* these updates into their local copy. These are all terms you'll get familure with as we go through this guide.
The system also allows developers to work on code simultaneously as each developer *checks out* a local copy of the *repository* to make their changes on. These changes can then be *committed* back to the central repository and other developers can *pull* these updates into their local copy. These are all terms you'll get familiar with as we go through this guide.
Developers can *branch*, *fork* and *merge* repositories allowing flexible workflows to happen, we'll cover these concepts in the documents and video's that follow.
@ -16,7 +16,7 @@ To understand all these terms lets first look at a git repository and its stages
We can think of this in four main areas, your working directory, a staging area, the local repository and the remote repository. Now depending on if the remote repository already exists depends on if you run a ```git init``` or a ```git clone``` command, and these commands kind of do what they sound like. Init sets up the necessary files to start tracking the changes in a **new** repository on the local file system, where as clone pulls all the current content from the remote repository and copies it to your local repository and sets up your working directory also. If you want to get changes from the remote repository that someone else has uploaded you can run *pull* to bring those changes into your working directory.
The staging area comes into play as an intemediate space that sit's between working directory and local repository. A developer *adds* changes to the stage area, if theyare happy with the change they *commit* the changes to the local repository and then when they are happy can *push* those changes to the remote repository. Lets try and visualise this in the diagram below.
The staging area comes into play as an intermediate space that sits between working directory and local repository. A developer *adds* changes to the stage area, if they are happy with the change they *commit* the changes to the local repository and then when they are happy can *push* those changes to the remote repository. Lets try and visualise this in the diagram below.
```mermaid
flowchart TD
@ -30,7 +30,7 @@ flowchart TD
## Sync Issues
When working with other developers you're all going to be cloning and pulling the code fromt he rmeote repository to start with and then committing and pushing your changes back. Now this is where it can get messy. Let's say theres 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 whats 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 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.
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.
@ -38,9 +38,9 @@ A good way to minimise this happening to you is to frequently run ```git pull```
## Branches
In a git repository you have a **main** branch. This is where you keep the current code, normally the current working code. When you develop new features, often team members work on these in parrallel to each other and you guessed it they don't want to be dealing with loads of merge conflict issues. Luckily, theres a way to avoid this by using a feature called **branch**. This lets you take a point in time copy of the repository and work onthe code, adding, commiting and pushing files as you please, without breaking things for others. Now when you are ready to move your code into the main branch you do something called a merge, often called a merge request(MR) or pull request(PR) - (these are the same thing). What git does here is move your new files into the main branch and if there are any merge conflicts on files that already existed you'll get teh options to handle them like before. You can switch between branches using the **branch** and **checkout** commands.
In a git repository you have a **main** branch. This is where you keep the current code, normally the current working code. When you develop new features, often team members work on these in parallel to each other and you guessed it they don't want to be dealing with loads of merge conflict issues. Luckily, there's a way to avoid this by using a feature called **branch**. This lets you take a point in time copy of the repository and work on the code, adding, committing and pushing files as you please, without breaking things for others. Now when you are ready to move your code into the main branch you do something called a merge, often called a merge request(MR) or pull request(PR) - (these are the same thing). What git does here is move your new files into the main branch and if there are any merge conflicts on files that already existed you'll get the options to handle them like before. You can switch between branches using the **branch** and **checkout** commands.
Let's try and visualise this in the diagram below showing we have a main branch and two feature branches called A and B, these branches are taken at different times from the main branc. We can also see that Feature A gets merged back into the main branch. Now you'll also notice numbers next to each dot int he diagram. These are the UID's for the commits you make. These are super important because it means you can roll back to a previous version of the code by using that UID at any time!ß
Let's try and visualise this in the diagram below showing we have a main branch and two feature branches called A and B, these branches are taken at different times from the main branch. We can also see that Feature A gets merged back into the main branch. Now you'll also notice numbers next to each dot in the diagram. These are the UID's for the commits you make. These are super important because it means you can roll back to a previous version of the code by using that UID at any time!
```mermaid
gitGraph
@ -67,11 +67,11 @@ gitGraph
commit
```
Using branches to manage your code is often reffered 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.
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.
### HEAD
The most recent commit on the currently checked-out branch is indicated by something reffered 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.
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.
If you have a branch checked out HEAD points to the latest commit on that branch.
@ -94,23 +94,23 @@ gitGraph
## Forks
Forks are kind of like branches, but instead of just making a slight deviation from main you actually get a full working repostity of your own. Making commits and pushes will only ever effect your git repo however there is a tie back to the original repository that allows you to pull updates from upstream. Developers can then make merge/pull requests backup stream to the main project. This is particularly useful if you want to make contributions to some code that doesn't belong to your team so you can't create a branch on the main repo. This is known as the Forking Workflow.
Forks are kind of like branches, but instead of just making a slight deviation from main you actually get a full working repository of your own. Making commits and pushes will only ever effect your git repo however there is a tie back to the original repository that allows you to pull updates from upstream. Developers can then make merge/pull requests backup stream to the main project. This is particularly useful if you want to make contributions to some code that doesn't belong to your team so you can't create a branch on the main repo. This is known as the Forking Workflow.
There are other workflows however such as the Gitflow Workflow which involves having several long lived branches such as main, develop and release branches. You can also completely ignore all these features and do something called Trunk-Based development where everyone commit's to main, and this is good for rapid itteration but can give you merge conflict nightmares!
There are other workflows however such as the Gitflow Workflow which involves having several long lived branches such as main, develop and release branches. You can also completely ignore all these features and do something called Trunk-Based development where everyone commits to main, and this is good for rapid iteration but can give you merge conflict nightmares!
![Git Merge Conflicts](./img/merge.gif)
## Getting Setup
Right thats enough theory lets get you set up to start with! The commands I'm about to show you will work on MacOS, Linux or windows. You first need to make sure you have git installed on your system, which you can get from [here](https://git-scm.com/). On MacOS and Linux you can then use your native terminal to run the ```git``` command and on windows you'll want to open the git bash program.
Right that's enough theory lets get you set up to start with! The commands I'm about to show you will work on MacOS, Linux or windows. You first need to make sure you have git installed on your system, which you can get from [here](https://git-scm.com/). On MacOS and Linux you can then use your native terminal to run the ```git``` command and on windows you'll want to open the git bash program.
## Username and Email
When you pull a private repository or push to a repository you have two options use HTTPS or SSH. You should use SSH where possible, HTTPS can be used when you are cloning someone elses work to use but don't intend on pushing back to that repository.
When you pull a private repository or push to a repository you have two options use HTTPS or SSH. You should use SSH where possible, HTTPS can be used when you are cloning someone else's work to use but don't intend on pushing back to that repository.
Now hopefully you'll have a login to [Gitlab](https://gitlab.com) or [Github](https://github.com) if not go and set one up now.
The first thing you'll need to do is set up your name, so git can use this to show to other who commited the code. Simply run the following in your terminal.
The first thing you'll need to do is set up your name, so git can use this to show to other who committed the code. Simply run the following in your terminal.
```bash
git config --global user.name "Ric Harvey"
@ -175,8 +175,10 @@ Now we need to use your public key with repository host normally Gitlab or Githu
To ensure you’re connecting to the correct server, check the server’s SSH host keys fingerprint. For:
GitLab.com, see the SSH host keys fingerprints documentation.
GitLab.com or another GitLab instance, see gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints where gitlab.example.com is gitlab.com (for GitLab.com) or the address of the GitLab instance.
```
GitLab.com, see the SSH host keys fingerprints documentation.
GitLab.com or another GitLab instance, see gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints where gitlab.example.com is gitlab.com (for GitLab.com) or the address of the GitLab instance.
```
- Open a terminal and run this command, replacing gitlab.example.com with your GitLab instance URL:
```
@ -339,7 +341,7 @@ To add a GPG key to your user settings:
<summary>Instructions for Github</summary>
- SIgn into Github
- Sign into Github
- In the upper-right corner of any page, click your profile photo, then click Settings.
- In the "Access" section of the sidebar, click SSH and GPG keys.
- Next to the "GPG keys" header, click New GPG key.

2
commit.md
View file

@ -19,7 +19,7 @@ git push origin your_branch --force
> Exercise caution when utilizing --force, as it has the potential to overwrite the history of the target branch. Its application on the main/master branch should be generally avoided.
As a rule of thumb it’s better to commit more often than not, to avoid losing progress or accidentally resetting the unstaged changes. One can rewrite the history afterward by squashing multiple commits or doing an interactive rebase.
As a rule of thumb it’s better to commit more often than not, to avoid losing progress or accidentally resetting the unstaged changes. One can rewrite the history afterwards by squashing multiple commits or doing an interactive rebase.
Use git log to show a chronological list of commits, starting from the most recent commit and working backward in time