Using_Git_Documentation

Using Git

by Siavas Firoozbakht at cern

Adding or amending pages

Git fundamentals

The following commands will be used from git in this scope:

git status : check for files that have changed
git add <path> (or git stage) : add files to the staged area for commit
git branch <new_branch> : create new branch
git checkout
- <branch> : move into <branch>
- -- <path_to_file_or_folder> : reset changes of file or folder (has to be unstaged)
git commit : commit files in the staged area
git merge <branch> : merge <branch> into the current one
git push origin <branch> : push the local commits of <branch> to its remote counterpart, so changes can be seen by everyone

Furthermore, these commands may prove useful:

git diff HEAD <path> : show changes in a file or folder
git log : show the commit history on the current branch

The usual workflow

Making new changes to the documentation can be achieved either by temporarily separating your workflow or by making changes directly to master branch (which is simpler).

The simpler method

The changes will be made directly on the master branch. Although this is the recommended option for the ones not very familiar with git, it may result in cumbersome merging of newer changes from other people with the local ones when the same lines in files are changed on both sides.

Follow these steps:

Open Git Bash and navigate with cd to the local repository
git status to check what has changed
git add ./file to add the desired files to the staged area
- git add --all can be used to add everything that has changed
git status to confirm everything is okay (should show desired file changes in green)
git commit -m "<your_message>" to commit the staged changes

git pull origin master to get latest updates from the remote

At this point you will either get everything neatly merged:

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git pull origin master
  remote: Counting objects: 9, done.
  remote: Compressing objects: 100% (9/9), done.
  remote: Total 9 (delta 4), reused 0 (delta 0)
  Unpacking objects: 100% (9/9), done.
  From https://gitlab.cern.ch:8443/sfiroozb/test_repo
  * branch            master     -> FETCH_HEAD
  7476706..a9c4379  master     -> origin/master
  Merge made by the 'recursive' strategy.
  docs/another_changed_file.md | 48 ++++++++++++++++++++++++++++++++++++++++++--
  third_file.md                | 37 ++++++++++++++++++++++++++++++++++
  2 files changed, 83 insertions(+), 2 deletions(-)
  create mode 100644 third_file.md

If so, run git push origin master to make the changes available to everyone on the remote.

Otherwise files with merge conflicts will be shown which have to be solved manually:

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git pull origin master
  remote: Counting objects: 3, done.
  remote: Compressing objects: 100% (3/3), done.
  remote: Total 3 (delta 1), reused 2 (delta 0)
  Unpacking objects: 100% (3/3), done.
  From https://gitlab.cern.ch:8443/sfiroozb/test_repo
  * branch            master     -> FETCH_HEAD
  820fc58..975a651  master     -> origin/master
  Auto-merging my_changed_file.md
  CONFLICT (content): Merge conflict in my_changed_file.md
  Automatic merge failed; fix conflicts and then commit the result.

In this case, solve the conflicts by keeping what is needed from remote and local changes (most of the times both parts have to be kept). Visual Studio Code has nice highlighting for helping with this. These conflicts are shown in files as following:

  <<<<<<< HEAD
  these are some
  new changes
  in this file
  which won't
  be on the remote
  =======
  And these are
  some other changes
  which were written
  on the remote.
  >>>>>>> 1ec67c262ec4d273c3b1756f294d38553abd64fe

The <<<<<<< HEAD, ======= and >>>>>>> commit_sha parts have to be removed. After solving all conflicts, run git add for the conflicted files and git commit which will prompt you for the commit message. This can be left as it is or edited after pressing the INSERT button. To complete the commit press ESC, write :wq and press ENTER to commit:

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master|MERGING)
  $ git add my_changed_file.md

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master|MERGING)
  $ git commit # Will prompt for commit message here
  [master ef1c6c3] Merge branch 'master' of https://gitlab.cern.ch:8443/sfiroozb/test_repo

Finally, run git push origin master to make the changes available to everyone on the remote.

The conventional method

The changes will be firstly committed to a branch, after which they will be merged locally in master and finally synchronised with the remote.

Follow these steps:

Open Git Bash and navigate with cd to the local repository
git status to check what has changed
git branch <new_branch> to create your new branch
git checkout <new_branch> to move to your new branch
From here, make changes and commit as many times as needed on your branch with the following commands (note that all these changes will not be available yet for everyone):
- git add ./file to add the desired files to the staged area
  - git add --all can be used to add everything that has changed
- git status to confirm everything is okay (should show desired file changes in green)
- git commit -m "<your_message>" to commit the staged changes
  - Use git commit -m "<your_message>" -m "<your_description>" to add a description as well

Afterwards, to make all the changes on the branch available to everyone:

git checkout master to go back on main branch
git pull origin master to get the most recent commits from remote
git merge <new_branch> to merge your branch

At this point you will either get everything neatly merged:

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (my-branch)
  $ git checkout master
  Switched to branch 'master'

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git pull origin master
  remote: Counting objects: 5, done.
  remote: Compressing objects: 100% (5/5), done.
  remote: Total 5 (delta 3), reused 0 (delta 0)
  Unpacking objects: 100% (5/5), done.
  From https://gitlab.cern.ch:8443/sfiroozb/test_repo
  * branch            master     -> FETCH_HEAD
  5d7aa12..a82a602  master     -> origin/master
  Updating 5d7aa12..a82a602
  Fast-forward
  docs/another_changed_file.md | 12 ++++++++++--
  third_file.md                | 35 +++++++++++++++++++++++++++++------
  2 files changed, 39 insertions(+), 8 deletions(-)

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git merge my-branch
  Merge made by the 'recursive' strategy.
  my_changed_file.md | 8 ++++++++
  1 file changed, 8 insertions(+)

If so, run git push origin master to make the changes available to everyone on the remote.

Or will have merge conflicts which have to be solved manually:

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (my-branch)
  $ git checkout master
  Switched to branch 'master'

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git pull origin master
  remote: Counting objects: 3, done.
  remote: Compressing objects: 100% (3/3), done.
  remote: Total 3 (delta 2), reused 0 (delta 0)
  Unpacking objects: 100% (3/3), done.
  From https://gitlab.cern.ch:8443/sfiroozb/test_repo
  * branch            master     -> FETCH_HEAD
  78ffdeb..7e5f415  master     -> origin/master
  Updating 78ffdeb..7e5f415
  Fast-forward
  my_changed_file.md | 19 +++++++++----------
  1 file changed, 9 insertions(+), 10 deletions(-)

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master)
  $ git merge my-branch
  Auto-merging my_changed_file.md
  CONFLICT (content): Merge conflict in my_changed_file.md
  Automatic merge failed; fix conflicts and then commit the result.

In this case, solve the conflicts by keeping what is needed from remote and local changes (most of the times both parts have to be kept). VS Code has nice highlighting for helping with this. These conflicts are shown in files as following:

  <<<<<<< HEAD
  these are some
  new changes
  in this file
  which won't
  be on the remote
  =======
  And these are
  some other changes
  which were written
  on the remote.
  >>>>>>> 1ec67c262ec4d273c3b1756f294d38553abd64fe

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master|MERGING)
  $ git add my_changed_file.md

  sfiroozb@teknopack-cda MINGW32 /d/Projects/test_repo (master|MERGING)
  $ git commit # Will prompt for commit message here
  [master b5de1a2] Merge branch 'my-branch'

Finally, run git push origin master to make the changes available to everyone on the remote.

Other useful tips

To exit the scroll mode from commands such as log and diff, press q.
Note that git commit commits your change into your local git. In order to get it into GitLab, you need to run “git push”. Here is the same including the output that you should see, and with an additional “git status” command to show the intermediate status:
Other useful editors for Markdown would be Typora for WYSIWYG desktop editing (therefore shows changes instantly in localhost) and SlackEdit for online WYSIWYG.