Week 4 Discussion - Git and Github & Nephology

What are Git and GitHub?

Exercise 105

1. What does tracking changes in context of Git mean?

2. Why is it important?

Solution to

1. It means to follow what is going on in the project files.

2. Some projects are developed over a long time with many collaborators. In such a project it is advantageous to isolate important changes to the project (e.g., you appended some text) and describe your changes (e.g., corrected typos). Some advantages are:

   1. You know what your collaborators do.

   2. If at some time an unexpected error happens, you may be able to track it to a specific change and remove it.

Exercise 106

1. What is the difference between Git and Github?

2. Do you know other sites similar to Github?

Solution to

1. Git is a tool to track changes in text-based files. Github is a service which offers remote Git repositories and other collaboration tools around a Git repository (e.g., issues tab where you can file bug reports for a project). Github uses Git.

2. Gitlab, Bitbucket, even your university may have a local Git service, e.g., mygit @THD

Exercise 107

What does the following quote mean in the context of git?

Your closest collaborator is you six months ago, but you don’t reply to emails.

Solution to

Git is typically used to collaborate with others, but git can also assist you even you are working alone in a project.

Imagine you begin a project but after a while you need to get other priorities done. After six months you want to continue your former project but cannot remember your last state. In this moment you would wish that you could speak with yourself six months ago, but you cannot send to your former self an email.

You can use git also as a project diary which may assist you in a long-lasting project.

For the source of this quote look at this post

Setting Up Git and GitHub

Exercise 108

How did you install Git?

A. Was already installed. A. Using apt A. Using homebrew A. Using a graphical installer A. Other

Solution to

I installed it using pacman which is a package manager like apt.

Exercise 109

Before we can create a change using Git (called commit) we have to provide a name and email. What could be the reason?

Solution to

Git is a collaboration tool, and many people can participate in a project. Every change that you do will be annotated with your name and email. This way callaborators can see who changed what.

Getting Started with Git

Exercise 110

You are working in a directory.

1. How can you start tracking these files in Git?

2. How can you see if a directory is tracked by Git?

Solution to

1. git init
   git add FILES-YOU-WANT-TO-TRACK
   git commit -m 'Initial files'
   

2. You probably have noticed the message after git init:

   Initialized empty Git repository in ... .git/
   

   Git typically uses the directory .git to store Git-relevant files (for tracking for instance). This is the repository. If this subdirectory exists in a directory, then this directory will very likely tracked by Git.

Exercise 111

After some time you want to continue with your personal project that you track using Git.

1. Which command would be helpful to see the current status of tracking?

2. The status indicates that you have a change to be committed. Which language does Git use to describe this?

Solution to

1. git status

2. to stage. Similar to put something in an area before modifying the repository. A graphical representation can be found on What does ‘stage’ mean in git.

Exercise 112

Imagine that you have a repository with a text file and a directory, which contains many photos.

# Create an example repository
mkdir my-diary; cd my-diary
git init
echo My dairy > diary.txt
mkdir img
curl https://picsum.photos/200 -sLo img/IMG_9217.jpg
curl https://picsum.photos/200 -sLo img/IMG_9218.jpg
git add .
git commit -m Initial

1. What do the following commands do?

   cd my-diary
   sed -i 's/dairy/diary/g' diary.txt
   git commit diary.txt -m 'fixed typos'
   git mv img/{IMG,2020-12-04}_9217.jpg
   git mv img/{IMG,2021-11-xx}_9218.jpg
   git commit -m 'annotated image dates'
   

2. What do a commit and to commit mean?

3. What would happen if we would run the third line without the argument diary.txt?

4. How can we alternatively commit the changes in diary.txt?

5. Why could have the user used two different commits instead of a single one?

Solution to

1. The user fixes typos in diary.txt and augments the photo filenames with their date. These two changes are committed separately to the repository.

2. Commit is an isolated modification of the project which typically carries a description of the modification. To commit means to add a commit to the repository by executing git commit ...

   A commit can also be seen as a minor milestone, as described in the book.

3. Git is not going to commit anything, because we have to stage the changes that we want to commit, unless we use git commit directly on a file like in this line. git commit FILE directly adds content to a commit (without the staging step)

4. • Staging can be done by git add diary.txt command

   • Alternatively: git add -u stages all updated files which belong to the repository.

   After staging, we can use git commit.

   Note that creating a file in the directory, e.g., mkdir src does not automatically stage a file. This has to be done manually using a Git command.

5. Because the two commits are unrelated to eachother.

   This may seem tedious compared to a single commit, but has the advantage that these commits can be individually undone if required in the future..

Exercise 113

You committed your changes but forgot to add an additional file to your commit. How can you amend your changes?

Solution to

Using git reset --soft HEAD~

Important Git Features

Getting Help, Logs, and Diffs

Exercise 114

You are working on a Python project and use Git to track your changes. Before calling it a day you want to commit your changes. You see that you modified many files but forgot what. Which command is useful to see your changes to create appropriate commits?

Solution to

Two ways:

• git diff to see all your changes to the last commit

• git status to see which files you modified, then git diff FILE

Exercise 115

You forgot what the -A option in git add -A does. How can you look that up?

Solution to

• internet search. Note that searching for git add -A may not work as the minus symbol in -KEYWORD typically means that the results should not contain pages about KEYWORD. Better search for git add A

• man git-add

• git help add

Ignoring Files

Exercise 116

You are working on a Git repo. Your text editor has a backup feature, which saves the files that you are working with using the name FILENAME.EXTENSION.bak. These files clearly should not be committed. How can you solve this problem?

Solution to

You could pay attention to never stage .bak files. Better solution is to tell Git to ignore these files using an .ignore file:

echo '*.bak' > .gitignore

Note that you do not have to commit .gitignore file. Committing and thus making the .gitignore file could be helpful though if the project itself creates some files that should be ignored, e.g., some log files like file.log. Then everyone who works on this repository would profit from the .ignore file.

Branching

Exercise 117

You are participating in a software project in your company and your team uses Git. You and your partner propose a major change to your team which introduces several modifications in the graphical user interface (GUI) of the software. You do not want to break the software while working on the new features.

1. How can you leverage branches for this purpose?

2. You tested your shiny GUI, demonstrated it with pride to your team and your team welcomed that. Which commands would you use to integrate the new features to the software?

Solution to

1. You can introduce a new branch (e.g. using git branch gui_version2) for the GUI improvements which will act as a collaborative sandbox for the new features. Writing complex software requires typically thorough testing. This way you will not be affecting the working (production) version of the software before you tested your functions thoroughly.

2. git checkout main
   git merge gui_version2
   # if conflicts present: resolve conflicts and commit.
   

Github

Exercise 118

When you are creating a new repository on Github, you have the following options:

Public

Anyone on the internet can see this repository. You choose who can commit.

Private

You choose who can see and commit to this repository.

1. When would you choose which option? Give an example.

2. What are the pros and cons of settings your repo public/private?

Solution to

1. If you want to share your projects with others, then you would choose Public. Then everyone will be able to copy and tinker with your work. You would choose Private, if you want to make your project only available to:

   • you

   • to the company behind Github

   • an exclusive group people (optional).

   Imagine you are working on a tool which automatically searches for specific mutations in biomedical databases and outputs statistics about their popularity as a hobby. You would share it with others, because

   • someone could find it useful

   • you are using many open source projects like Firefox and Libreoffice anyway and you want to give back to the open source community

   • you are interested in the feedback or bug reports (the errors in your software) of others

   Now imagine that you are working on the same software project in a company. The company wants to keep this tool advantage for itself to be better than its competitors in the market. But the company decided to use Github as their collaboration platform, because Github offers helpful features for collaboration and the company trusts Github. Then you would have to keep your repository private.

   Note that the company could make only the compiled version (e.g., the .exe file) without its source code publicly available. Without the source code, others won’t be able to adapt the software for their purposes.

2. Some pros of making your project public:

   • others can use it or leverage your tool to create another tool

   • others can contribute to your project

     • writing code

     • testing your tool and giving you feedback (e.g., bug reports, enhancement ideas)

   Some cons of making your project public:

   • effort/cost of making it public

   • chance of receiving feedbacks/issues about your code (note that issues can be deactivated on Github, and you can hide your mail address)

   • you do not have the information/tool advantage over others, you may not be able to sell your tool

   The pros/cons of making your project public could be seen as vice versa.

   Note that these lists are not comprehensive and the significance of pros/cons depend on your (business) strategy (e.g., if you want to sell your product, or if you want to give something back to the community).

Finally you may have thought about the term open source while reflecting about the keyword public. An important part of open source is giving permission to use the source code or design documents of your product. See WP: Open source for details.

Exercise 119

When you are creating a new repository on Github, you have the following options for initializing your project:

1. Add a README file

2. Add .gitignore

3. Choose a license

What are the advantages of adding these files to your project?

Solution to

1. README is like a instruction leaflet for your project. It should at least include information about which problem your project solves. Many projects give some simple examples how to get started – especially if it is software library or a command line tool. Sometimes the examples tell much more about your project than your description. In overall, README describes your project so that the user does not have to try it out or look into its source code to understand what your project does. More info: About READMEs

2. Many software projects create additional files while editing the software, compilation or usage, e.g., logs. Many of them could be irrelevant to build your project. If you describe these files in .gitignore, git does not show these in git status and clobber your view.

   Making irrelevant files part of the repo could confuse the user of the project, because the project contains irrelevant files for building your tool — compare it to cooking a recipe on a kitchentop full with unnecessary things. Another advantage is that you would know which files to tinker with if there is a bug with your project. More info: Ignoring files

3. Making your project public does not mean that others may

   • share it

   • modify and share it (create derivative works)

   • sell it

   If you include a license then the users of your work will be clear about your preferences without manually asking for permission to use it elsewhere or create other work based on your work. More info:

   • The legal side of open source

   • Licensing a repository

Exercise 120

1. What is the difference between a local and remote repository?

2. When would you use a remote repository?

Solution to

1. A repository is local, if you it resides on your computer. A remote repo is typically on a computer which many users have access to.

2. • for collaboration

   • for sharing

   • for backing up your project

Markdown

Exercise 121

1. What is Markdown?

2. What is its advantage?

Solution to

1. Markdown is a popular markup language. Literally to mark something up means to highlight parts of text using a pencil or marker pen. The meaning of markup in computing probably derives from that: You use special symbols in your written text to include stylistic information. A written text has typically content, structure and form (style). Using Markdown you can augment your content with form and structure.

2. Using Markdown we can describe documents in a minimalistic way. This paves the way for easily diffing modifications in the document or automatically creating documents. For example, this content is actually written in Markdown, which is automatically converted to HTML. Using a converter tool like Pandoc you can even create books or slideshows.

   In recent years Markdown became the Lingua franca for documents written in plain text. Knowing how to write Markdown is similar to the advantage of speaking English on many websites.

   Interesting fact: Similar to spoken languages Markdown has many dialects, in other words flavors. One of the popular ones is CommonMark.

Exercise 122

Mark up the following text in Markdown. Use Markdown’s markup features wherever you can.

You can directly work on an interactive editor like Markdown Editor

2021-11-12

Morning

Woke up very early at 4 with heavy eyes. Probably I am stressed. It could be related to:

deadlines at work
my stressful phone call with my mother

I listened to the podcast Short Stuff: Your Dirty Bed to fall into sleep again

https://www.iheart.com/podcast/105-stuff-you-should-know-26940277/episode/short-stuff-your-dirty-bed-89082486/

Afternoon

The following Bash code creates random files with random content, lovely!

for i in {1..10}
do
    echo $RANDOM > $(mktemp XXX.txt); echo $i
done

The command mktemp generates random files, and $RANDOM expands to a random integer.

Evening

Now I know how T-Shirts are designed 😀:

https://img-9gag-fun.9cache.com/photo/4077402_700bwp_v1.webp

vocabulary: to bring so. up to speed means to make sure that someone has all the latest info about something.

Solution to

Markdown code:

# 2021-11-12
## Morning

Woke up very early at 4 with heavy eyes. Probably I am stressed. It could be related to:

- deadlines at work
- my stressful phone call with my mother

I listened to the podcast Short Stuff: [Your Dirty Bed to fall into sleep again](https://www.iheart.com/podcast/105-stuff-you-should-know-26940277/episode/short-stuff-your-dirty-bed-89082486/)

## Afternoon

The following Bash code creates random files with random content, lovely!

```bash
for i in {1..10}
do
    echo $RANDOM > $(mktemp XXX.txt); echo $i
done
```

The command `mktemp` generates random files, and `$RANDOM` expands to a random integer.

## Evening

Now I know how T-Shirts are designed 😀:

![](https://img-9gag-fun.9cache.com/photo/4077402_700bwp_v1.webp)

vocabulary:

- *to bring so. up to speed* means to make sure that someone has all the latest info about something.

To render this code (e.g., by converting to HTML) you can use a Markdown Editor.

Pull requests

Exercise 123

What is the difference between a pull request and git merge?

Solution to

A pull request is done on GitHub. git merge is a Git command, and works on the local repository.

Pull request is part of social coding. For instance, it is typically followed by discussions if the pull request should be accepted. The tool Git does not have such a feature.

Exercise 124

Imagine you have accepted a pull request on GitHub and merged the changes into your main branch. Then you continue to work on your local repository on the main branch, but you cannot see the merged changes. What could be the problem?

Solution to

The merge modified the remote repository. To bring your local repository up to speed with the latest change, you have to git pull.

Pages

Exercise 125

When you are creating GitHub pages for your repository you have the option to select a theme. How it is possible that the same Markdown code looks differently for different themes?

Solution to

In Markdown we describe the content, structure and some weak style information like emphasis (*italic*, **bold**), but Markdown does not define any colors, font size or where the text exactly appear on a webpage. This allows the content to be rendered in various styles.

In this context, Markdown is similar to HTML. HTML describes content and structure, where CSS is contains form (i.e., style).

GitHub uses the static website generator Jekyll to generate your GitHub pages.

Exercise 126

Look at GitHub Pages. What is the advantage of creating a repository called USERNAME.github.io over activating GitHub Pages for a repo?

Solution to

On GitHub every repository can have its own GitHub Pages which can act as project documentation. These are then available under USERNAME.github.io/repo-name.

If you want to create web pages about you, then creating a repository USERNAME.github.io is more appropriate. Then your personal webpage is accessible at USERNAME.github.io.

Forking

Exercise 127

GitLab is an alternative to the Git management software GitHub. GitLab calls pull requests merge requests.

Create a merge request for the following repo, which uses GitLab:

https://mygit.th-deg.de/lsi/the-unix-workbench-notes

Your merge request could contain for instance:

• an improvement of a solution

• fix for a typo

• an additional line on the guest book

Solution to

Steps:

• fork. For details: GitLab docs: Creating a fork

• clone the project

• make your contribution

  • clone the project on your shell, modify/add a file, push your changes

  • or, modify/add a file directly on the web interface

• create a merge request. For details: Gitlab docs: Creating merge requests - When you work in a fork

Summary and reflection

Did you reach the following learning objectives for this week? Discuss with your partner.

• Use Git to track versions of code

• Use GitHub to create a remote Git repository

• Create Git branches

• Fork GitHub repositories and open a pull requests