# CFG: How to Git for your projects

Pre-requisites: you need to have your terminal working, a GitHub account, and have installed git.

## Set up your remote repository

:bulb: Remember, this is the place where your code will be stored, and where you can share it from (like Google Drive).

1. Go to Github and click the green "New" button:


2. Give the repository a name:


3. Ignore all the other boxes and click "Create repository"


4. You should get to this page:


---

## Initialise your local code folder as a git repository

1. In your terminal, navigate to your project folder using `cd` and `ls`. (or make a code folder if you're starting from scratch)


2. Create a file in your code folder using `touch`, e.g. `touch index.html`. (Or if you already have files there, skip this).

3. Initialise your git repo locally (i.e. tell git that your code folder is one to keep track of) - in your terminal, make sure you are in your code folder, and type `git init`.

4. If this has worked, it should say something like `Initialised empty Git repository in /home/jo/Documents/code-first-girls/.git/`.

## Stage your files

1. Type `git status` to check that it all looks ok so far - you should see your files listed in pink or red, under the heading "Untracked files". This means that git knows you have changes to your code, but you haven't staged or committed them yet.


2. *Stage* your files by typing `git add <your_file_name`. (don't copy the `< >`, e.g. `git add index.html`)

3. If you type `git status` again, you should see that your file has moved to the staging area. It will probably have changed colour to green, and will be under a heading that says "Changes to be committed".


## Commit your changes

1. Now that you have changes in your staging area, you can bundle them up into a git commit. Do this by typing `git commit -m "My message describing what changes I made"`, but replace the message with your own.


2. You might get a message at this point asking for your identity:


If so, type the commands that it tells you to sort this out:


(note I've got a special email address here, it should work for you with your normal email that you use for GitHub)

If it gives you no output, that means it has worked (terminals often have "silent success").

3. Try your commit again if you need to. If your commit has worked, you should get this output:


4. You can check your git log to see your commit using `git log`:


## Pushing your changes to GitHub for the first time

1. You can see that for me it says "on branch master". It is best practise to change that branch to be called "main" instead, so I'm going to do this now with `git branch -M main`.

I can prove that this worked by doing `git status`:


2. Go back to Github, and find the instruction that starts with `git remote add origin`. This is the command to link your local repository with your remote repository.


3. Copy and paste this into your terminal. It should not give you any output.

4. Now you're ready to push your commit up to GitHub for the first time. Type `git push -u origin main`. It might ask you for your GitHub username and password, so type these in and press enter.

5. If it has worked, you should see some output that starts with "Enumerating", and ends with `Branch 'main' set up to track remote branch 'main' from origin`:


If instead you get an error saying "fatal, authentication failed", then unfortunately you need to some extra annoying setup for SSH. See below for instructions on this.

---

6. (if you needed to) When you've set up SSH correctly, you should be able to go back to GitHub and try the `git remote add` command again, except this time, you need to use the SSH version of it:


7. If you get an error: `fatal: remote origin already exists`, first run `git remote remove origin`, and then your new `git remote add` command:


8. Now try pushing to your remote repo:


---

9. If it worked, congratulations! You have successfully created a remote repo, a local repo, and got them in sync with each other! :tada: If you go to GitHub and refresh the web page, you should see your local code displayed in the remote repo:


10. Now you are ready for others in your team to collaborate with you. See the next section for instructions on how they can clone your repository, and contribute to it.

---

## Collaborating with others: cloning a repo

1. To contribute to someone else's repository, first you need to be added as a collaborator. To do this, the owner of the repo needs to go to the settings, Collaborators (under Access) and Add people:

Go to settings:

Go to collaborators:

Add people:

You should get an email inviting you to collaborate on their repository.

2. Once added as a collaborator, go to the main page of the repository, and click the green Code button:


3. You should get a pop up which has the repo's URL for you to copy:


4. First try clicking on HTTPS and copy that link - the link itself should start with `https://`.

5. Go to your terminal, navigate to a suitable place for the folder to be copied to (e.g. for me, I do `cd Documents/Code/CFG2022/`).

6. Type `git clone <the_link_you_copied` (but replace `<the_link_you_copied>` with the link from GitHub.)

7. If you get an error saying "fatal, authentication failed", then try going back to GitHub, click `SSH` instead of `HTTPS` and try `git clone` again, with the ssh link instead (it will begin with `git@github`.

8. If you still get the authentication error, then unfortunately you need to some extra annoying setup for SSH. See below for instructions on this. Once you've done that, try git clone with the ssh link once more.

9. If it worked, then you should be able to run `git status`, `git add`, `git commit` and `git push` to make changes to the codebase, and push them to GitHub too!

---

## Collaborating in general using Git

This section is for you if you and your team mates have successfully got one repo on GitHub between you, and you all have a local copy of it on your computer (i.e the people who didn't create the repo have all cloned it successfully).

1. When you start doing some work on your shared repository, first run `git pull` to pull down any changes from GitHub that your team mates have pushed up in the meantime. Here's an example from my work of what it looks like when your team mates **have** made changes, **and** when they have been successfully automatically merged with my local copy of the repo:


2. If there are no changes, the output will say "Already up to date":


3. Sometimes when you `git pull` you will get a **merge conflict**. (It will say `CONFLICT` in capital letters. This happens when Git is unable to automatically merge your changes with the ones that someone else has done (for example, if the changes are quite similar). This means you will have to do the merge manually.


4. To resolve a merge, open your files in VSCode (you can do this easily from your terminal by typing `code .` if you have navigated to the project folder with `cd`). Look for sections of the code where there is a blue block and a green block next to each other, surrounded by `>>>>>` symbols:


5. Compare these blocks and figure out if you want just one of them, or both. In small writing above the blocks it gives you some options: "Accept current change", "Accept incoming change", "accept both changes". Click on the one of these that you want, and the blue/green blocks should disappear.

6. Check the rest of the files for any more merge conflicts, resolve them and then go back to the terminal.

7. Do `git status` and it should tell you what commands you need to run to finalise the merge (probably `git add` and `git commit`, like you've done before).

8. Now you can make code changes to your file. When done, do `git add`, `git commit -m "my message here"`, `git push`, and your changes should be saved and available for your whole team to see on Github.

9. If you get this yellow and red error (`updates were rejected`), run `git pull` first, then try `git push` again. Sometimes you will need to fix another merge conflict if again someone has pushed some work to the remote in the meantime:


---

## SSH Instructions

1. To fix the authentication issue, we're going to follow these instructions: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

I'll copy below the important steps.

2. 

(Remember, the `$` sign is an indicator that we are in the terminal for this diagram. This means you **don't** need to copy this symbol into the terminal. Just everything from `ssh-keygen` to the end)

3. 

For both of these steps, you should be able to just press enter to accept the default (i.e. accept the path it gives you, and enter nothing as a blank password)

4. 

This step means just type `eval "$(ssh-agent -s)"` in your terminal.

5. 

Type the command exactly as shown (but without the `$` symbol).

6. We then go to https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account to follow the next instructions there.

7. 
Use `cat` to display the contents of the ssh file we created from the previous commands (type the command from the screenshot without the dollar. It should start with something like `ssh-ed25519` and end with an email address.

8. In Github, go to your profile photo in the corner, settings, SSH and GPG keys, and click "New SSH key":


9. Give it a title (like "my laptop"), and then copy and paste the key output from your terminal into the key field (the stuff that starts with `ssh-` and ends with an email).

10. Press "add SSH key", confirm your password if prompted, and then you should be able to retry the commands you were doing before you got the `fatal: authentication error` (git push or git clone).