GIT Course

Version-control using Git

Git is a tool allowing you to easily work on a project. You will be able to go back to a previous version, and since the code will be hosted on a server, you will reduce the probability of losing all your work. You will also make projects in a team go smoother, are they are many features such as branches, issues, pull requests, which are quite convenient for programmers.

  • you will learn what's Git
  • the basic usage of Git
  • the main concepts
  • good practices
  • some advanced concepts

This course will strongly refer to GitHub, but you may also check

  • GitLab, the most well-know alternative to GitHub
  • Gogs, open-source, self-hosted (or Gitea)
  • Bitbucket, etc.

As a student, you may enjoy the benefits of the GitHub student pack.

edit 21/08/2021: A lot of content that was in this course (README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, ...), was moved to "Make Git project". This is because I wanted to separate a bit more the commands and the concepts 🙇. Still, I kept a short description here, for those that are not interested in the advanced or the proper way to use these files.


Introduction

Git is a great tool that allows users to work on one project together, by allowing things as

  • commits: a save of your project
  • branch: a copy of your project
    • usually the original is on the branch "master" or "main"
    • you're cloning it, creating a new branch, on which you'll work
    • then you are merging or dropping your changes

First, you need to

As a side note before starting, you can create aliases for a command like git name with the command git config --global alias.name 'a command' where a command could be add . or commit...


Basic usage

Please take note that every command is starting with "git", followed by one space.

So to summarize, a basic usage would be

# 
# Only done once, download the repository locally 
#
git clone "https://github.com/lgs-games/memorize.git"

# Then inside the folder, you can do

# get the latest version on the server
git pull
# ... work a lot ...
# check what changed
git status
# notify git that these files should be added
# to the save
git add .
# create a save named "I worked a lot"
git commit -m "I worked a lot"
# then send your saves=commits to the server
# (or you can repeat work->add->commit)
git push

As a side note

git add .
git commit -m "I worked a lot"
# is almost the same as (new files aren't added)
git commit -am "I worked a lot"

Main concepts

Here are commands that you will use on a project, if you are not working alone (you may also use it when working alone, if you're consistent).

  • git branch name: create a branch "name"
  • git checkout name: move to the branch "name"
  • git checkout -b name: create and move
  • git merge name: merge the current branch with the branch "name"
  • git branch -d name: delete a branch

By default, you are coding on a branch called master (or main). Let's explain what's a branch. If you're smart, you will want to always have a working version of your project ("main" here). In that case, if you want to add one functionality (let's call it "f1"),

  • you will copy your project in "f1": git branch f1
  • you will move to the copy: git checkout f1
  • [...] work on the copy (you can use add, commit, push, ...) [...]
  • you can go back to "main": git checkout main
    • delete the new copy git branch -d f1
    • or accept your changes git merge f1
      • if "main" didn't change, no problems, the copy replace "main"
      • but if "main" changed, then you may have to manually pick which parts of the two copies you want in the new "main" (=resolving conflicts).

As a side note, when you have to resolve conflicts, the merge command's output will list what files need to be reviewed. In each file, you have the two different versions and need to delete the code you don't want to keep. Some software provides you an interface to do that quite easily such as PHPStorm, or any software made by JetBrains.

Merge image - GitGraph.js

Note: if you think main is better than "master" then don't forget to add that to your config git config --global init.defaultBranch main.


Good practices

Atomic commits: one commit means one change, such as adding one functionality. Do not make hundreds of changes in one commit, making it hard to find what you did. You can select the lines of a file you want to commit using git add -p file.

Short-Long description: you should make a short and a long description of your commits, like that

git commit -m "a short inline description

A long description, where I further describe
what I did
"

README.md: put a README in all of your projects, that is the start of a great adventure.

LICENSE: you may also put a LICENSE even if you don't want to put restrictions on your code, to protect yourself from complaints (MIT LICENSE is good for that, or The Unlicense). You should pick your license here.

.gitignore: you may not want to commit some files like high-churn ones or big files... Create a file called "gitignore" is a good practice, you can


Advanced concepts

Here are some functionalities that you can find on GitHub, but you may find things similar (if not exactly the same) on GitLab or Gogs.

Note: I'm putting a lot of files in a folder .github, because it makes my root folder cleaner, but you can put the files directly in your root folder (😐). You can also replace UPPER_CASE names with lowercase names. You can use docs instead of .github.

This page Working Open Workshop is summarizing with a lot of pictures (issues, forking a repository, pull requests, etc.).


Git master

You may, like me, hear about these commands, so I'm adding them here, but unfortunately, I didn't use even one of them yet 🙄

Instead of providing a SHA1, you may use one of these shortcuts

  • HEAD: the last commit
  • @: the last commit
  • HEAD^: the commit before HEAD (not working well on Windows)
  • HEAD^n: the n-th commit before HEAD (not working well on Windows)
  • HEAD~n: the n-th commit before HEAD (same as ^)
  • SHA1: either the sort SHA1 such as 54b01d4a or the whole SHA1
  • HEAD@{two month ago}: the closed commit that we made after a date (you may add "" on Windows)
  • HEAD@{2021-05-05}: the closest commit after a date (YYYY-MM-DD) (you may add "" on Windows)
  • origin/master@{two month ago}: same as before, but we can add a branch

Fancy notes

Memorize - card


Cheatsheet

You may look at these cheat sheets


Sources