Merge pull request 'adds more links and some more verbose information to the readme.md file' (#3) from waldek/LinuxSysAdminsDoc:master into master

Reviewed-on: https://gitea.86thumbs.net/vl4dd/LinuxSysAdminsDoc/pulls/3

Git/readme.md

@@ -1,57 +1,106 @@
 # Git
+
 ## Description
+
 Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. 
 
-## Usefull links
+## Useful links
-- [Git Cheat Sheet](https://education.github.com/git-cheat-sheet-education.pdf)
+
+- a very handy [cheat sheet](https://gitea.86thumbs.net/waldek/LinuxSysAdminsDoc/raw/branch/master/Git/SWTM-2088_Atlassian-Git-Cheatsheet.pdf) in pdf outlines the basic Git commands to help you learn git, as well as more advanced concepts such as Git branches, remote repositories, undoing changes, and much much more
+- the main git [documentation](https://git-scm.com/book/en/v2) is an excellent reference manual
 
 ## Git System
+
+The diagram below outlines the main gt commands and how they relate to the version control system.
+In our classes the **local** is the repository on your own computer and the **remote** is the corresponding repository you create on our [gitea](https://gitea.86thumbs.net/) server.
+Nothing is stopping you from hosting your own gitea server or pushing your local repository to a third party server such as [gitlab](https://about.gitlab.com/).
+
 ![Git System](img/Git_Guide.png)
-= 
+
+A remote repository is often referenced by the name **origin** but this naming is fully up to you.
+If you would push to multiple remote locations you could for example add one named gitea for our own and gitlab for your gitlab account.
+
+```bash
+git remote add gitea https://gitea.86thumbs.net/USER/REPOSITORY.git
+git remote add gitlab https://gitlab.com/USER/REPOSITORY.git
+```
 
 # Basic commands
 
 ## Git clone
-Clone repo located at **\<repo>** onto local machine. Original repo can be located on the local filesystem or on a remote machine via **HTTPS** or **SSH**.
 
-> git clone <repo>
+Clone repo located at **\<repo>** onto local machine. Original repo can be located on the local file system or on a remote machine via **HTTPS** or **SSH**.
+Throughout the classes you'll first clone via HTTPS but once we'll learn about [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) you'll be able to clone, push and pull over SSH.
 
-## Git init
+```bash
-Initialize an existing directory as a Git repository
+git clone $REPOSITORY_URL
-> git init
 
-Create empty Git repo in specified directory. Run with no arguments to initialize the current directory as a git repository. 
+```
-
-> $ git init \<directory>
-= 
-
-## Git status
-List which files are staged, unstaged, and untracked.
-
-> $ git status
 
 ## Git config --global name & email 
-Must be identifiable for credit when review version history.
 
-> $ git config --global user.name “[firstname lastname]”
+Before you can use git you **need** to identity yourself.
+Git uses this information in each commit so we can keep track of **who** did **what** **when**.
 
-> $ git config --global user.email “[valid-email]”
+```bash
+git config --global user.name "$FISTNAME $LASTNAME"
+git config --global user.email "$EMAIL"
+```
+
+## Git init
+
+To initialize an existing directory as a Git repository you have to input the following command into a shell.
+On windows your best bet is to launch a **git bash** shell by right clicking in the folder.
+On linux you can just open a terminal, navigate to the desired directory and execute the command.
+
+```bash
+git init
+```
+
+If you want to create a new directory with git version control inside it you run the following command.
+
+```bash
+git init $DIR_NAME
+```
+
+## Git status
+
+List which files are staged, unstaged, and untracked.
+This gives you a good overview of the current state of you repository and hints towards which files you can or should stage.
+
+```bash
+git status
+```
 
 ## Git add 
-Stage all changes in **\<directory>** for the next commit. Replace **\<directory>** with a **\<file>** to change a specific file.
 
-> $ git add readme.md image.jpg 
+By staging files you put them in the list to be added to the next commit.
+You can add one or more files at the same time.
+Complete directories can also be added.
+
+```bash
+git add readme.md image.jpg
+```
 
 ## Git commit 
-Commit your staged content as a new commit snapshot
 
-> $ git commit -m "First Commit"
+You commit your staged content as a new commit snapshot with the following command.
+The message you include in the commit is fully up to you but as a general rule of thumb it should explain what the commit does.
+For example: this commit *"adds pictures to the asset folder"*
+Some projects have serious commit message [guidelines](https://www.datree.io/resources/git-commit-message), others not.
 
-After doing this, you may fix the identity used for this commit with:
+```bash
+git commit -m "$YOUR_COMMIT_MESSAGE"
+```
 
-> $ git commit --amend --reset-author
+If the identity is not correct you can fix this this the following command.
+
+```bash
+git commit --amend --reset-author
+```
 
 ## Git diff
+
 Show unstaged changes between your index and working directory.
 
 > $ git diff

readme.md

@@ -1,14 +1,24 @@
 # LinuxSysAdminsDoc
 
 ## Description
-Shared documentation for the brussels formation Linux Sys Admins group.
+
+Shared documentation for the Brussels formation Linux Sys Admins group.
 feel free to modify :)
 
 ## Topics 
+
+**The topics will link you to our documentation**
+
 ### [Git](https://gitea.86thumbs.net/vl4dd/LinuxSysAdminsDoc/src/branch/master/Git)
-- Cheat sheet  
+
-the basic Git commands to help you learn Git, and more advanced concepts around Git branches, remote repositories, undoing changes, and more.
+As git is one of **the** most used [version control](https://en.wikipedia.org/wiki/Version_control) systems we'll be using it in class for all note keeping.
-- [Git Exercices](https://gitexercises.fracz.com/)  
+
+- a very handy [cheat sheet](https://gitea.86thumbs.net/waldek/LinuxSysAdminsDoc/raw/branch/master/Git/SWTM-2088_Atlassian-Git-Cheatsheet.pdf) in pdf outines the basic Git commands to help you learn git, as well as more advanced concepts such as Git branches, remote repositories, undoing changes, and much much more.
+- the **exercise**, fracz, that we started in class can be found [here](https://gitexercises.fracz.com/). 
+- Hugo suggested [this](https://ohmygit.org/) game, programmed in the [godot](https://godotengine.org/) language as a nice way to **see** how git works, especially how branches can be visualized
+
 Online platform to learn and practice Git. Discover its features you might haven't been aware of. With all the exercises provided you will rapidly become a Git Master! 
+
 ### [Vim](https://gitea.86thumbs.net/vl4dd/LinuxSysAdminsDoc/src/branch/master/Vim)
-- Cheat Sheet
+
+- the classic vim [cheat sheet](https://vim.rtorr.com/)