Content from Introduction

Last updated on 2024-06-26 | Edit this page

Overview

Questions

  • What is Git?
  • What is the point of these exercises?

Objectives

  • Learn what is Git and why you should be using it

What is Git?

Let’s learn about Git Source Code Management (SCM) system, and why we all use it!

From the Git website:

Callout

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.

Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows.

Why should I use Git?

You should use Git for storing and sharing your work.

Your should use Git to version your code.

You should learn Git to be able to contribute to common projects.

What can I learn here?

This is not intended as a full tutorial: you will get familiar with some basic concepts, and do some hands-on exercising to gain confidence with Git. You will find links to full-fledged lessons, there are many of them!

Key Points

  • Git is a version control system.
  • It is widely used, it is the most popular source code management tool.
  • We will use Git during the hands-on sessions to store and share code.

Content from Learning Git

Last updated on 2024-06-25 | Edit this page

Overview

Questions

  • Where do I find tutorials on Git?

Objectives

  • Get an overview of existing Git tutorials

Is this a Git tutorial?

No, this is a hands-on session for you to exercise basic Git commands so that you do not have to do it with your real projects.

Take your time to do it now, not when you are busy finalizing your analysis code.

Git tutorials

Excellent Git tutorials exist, the teaching approach varies.

Where do we start?

Key Points

  • Excellent Git tutorials exist.
  • Take your time to work through them.

Content from Basic setup

Last updated on 2024-06-26 | Edit this page

Overview

Questions

  • Do you have Git installed?
  • How to configure Git?
  • How to connect to GitHub?

Objectives

  • Have Git installed
  • Configure Git user information
  • Create a GitHub account
  • Create a SSH key to authenticate to GitHub

Installing Git

Check if you have Git installed with:

BASH 

git --version

If not found, go to the offical Git download instructions and install Git. If you working on WSL2 Ubuntu, choose Linux/Unix, not Windows.

Configuring Git

You might have used Git without user configuration, e.g. when you just clone a repository from GitHub with git clone https://github.com/<XXX>/<YYY>.git. To be able to add code (“push”) in repositories, you will need to to configure user information.

Check if you have it already with:

BASH 

git config --list

If user.name and user.email appear in the list, user configuration is done.

If not, configure user information with

BASH 

git config --global user.name "[name]"
git config --global user.email "[email address]"

Replace [...] with your input, and keep the quotes around your name if there are spaces.

You can read more about configuring Git in https://coderefinery.github.io/git-intro/configuration/#configuring-git-command-line-and-editor

GitHub

Create a GitHub account

In this workshop, we will use GitHub as a “remote” repository. If you do not have a GitHub account yet, create one by following “Sign up” from the GitHub homepage. Note that the email address should match the one that you configured for local Git.

Generate a SSH key and add it to GitHub for authentication

To be able to push code to GitHub from your terminal, you will need to authenticate. SSH is the recommended method.

Check if you already have set it up:

BASH 

ssh -T git@github.com

It is done, if you get:

OUTPUT 

Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.

If not, follow these instructions:

Key Points

  • You need to configure Git user information for your local repository.
  • You can use an SSH key to authenticate your connection to GitHub from terminal.

Content from Exercises

Last updated on 2024-06-26 | Edit this page

Overview

Questions

  • How to create a repository?
  • What is local, what is remote?
  • How to push your updates?
  • How to use branches?
  • And many more…

Objectives

  • Have Git installed
  • Configure Git user name
  • Create a GitHub account
  • Create an ssh key to authenticate to GitHub

Create a local Git repository

Create a new directory, e.g. git-example

BASH 

mkdir git-example
cd git-example

You can turn it to a Git repository with

BASH 

git init

If you have not configured the default branch name, you will see this message:

OUTPUT 

hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint:   git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint:   git branch -m <name>

Exercise 1

If you got the output above, follow the advice in the message: change the branch name to main and configue your default initial branch name to main.

BASH 

git config --global init.defaultBranch main
git branch -m main

Check the status of the repository:

BASH 

git status

OUTPUT 

On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

Now add a new file to the directory. You can use the following:

BASH 

echo sometext > newfile.txt

Exercise 2

Check the status again and add the file to be committed as instructed in the Git messages.

Check the status:

BASH 

git status

OUTPUT 

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        newfile.txt

nothing added to commit but untracked files present (use "git add" to track)

Add the file (or a snapshot of it at this moment) to the “staging” area with

BASH 

git add newfile.txt

Make a version of the repository, i.e. commit the new file with

BASH 

git commit -m "First version of newfile.txt"

OUTPUT 

[main (root-commit) 0a0951c] First version of newfile.txt
 1 file changed, 1 insertion(+)
 create mode 100644 newfile.txt

Flag -m is followed by a commit message. When things go wrong, you will learn to appreciate clear and descriptive commit message.

Exercise 3

Find the git command to check the version history. Use e.g. Git cheat sheet.

Won’t show it, find it yourself!

Modify the file, e.g.

BASH 

echo somenewtext >> newfile.txt

Now you can check the differences against the previous version:

BASH 

git diff

Exercise 4

Add and commit your changes as before.

BASH 

git add .
git commit -m "Update of newfile.txt"

Upload an existing local repository to GitHub

For now, your code is only in your local repository. You will now create a remote repository, so that you can store the code there and share it.

Go to your GitHub area (https://github.com/[yourgithubname]), choose the “Repositories” tab and click on New.

Choose git-example as the repository name, choose Public and leave other options as they are. This will create the repository and generate an instruction page, and you can copy the commands under the title “…or push an existing repository from the command line”.

Note that GitHub provides the command to change the branch name to main which we did already.

The git remote add... command

BASH 

git remote add origin git@github.com:[yourgithubname]/git-example.git

defines your new GitHub repository as the remote repository and names it as origin. This is a common choice and is used when pushing the code in the repository:

BASH 

git push -u origin main

The option -u links your local main to the remote main. Therefore you only need to do this once.

You can now check the remote repository location with:

BASH 

git remote -v

OUTPUT 

origin  git@github.com:[yourgithubname]/git-example.git (fetch)
origin  git@github.com:[yourgithubname]/git-example.git (push)

Check also that the code has appeared in the GitHub. If you still have the instruction page open, click on <> Code top-left to see the repository contents.

Optional exercise 5

Create a another GitHub repository following the instructions under the title “…or create a new repository on the command line”.

Note: create a new local directory first, do not nest Git repositories.

Go to your GitHub area (https://github.com/[yourgithubname]), choose the “Repositories” tab and click on New.

Choose git-example-web as the repository and leave other options as they are. This will generate an instruction page, and you can copy the commands under the title “…or create a new repository on the command line”.

You will notice that the commands are the same what we have done above. You can use these commands if you start from an empty directory.

Clone an existing repository from GitHub

Ask an another participant to provide you their GitHub repository address and clone it locally. As we all used the same name, plain cloning will fail with

BASH 

git clone git@github.com:[someoneelse]/git-example.git

OUTPUT 

fatal: destination path 'git-example' already exists and is not an empty directory.

Give it another name, e.g. git-example-friend

BASH 

git clone git@github.com:[someoneelse]/git-example.git git-example-friend

Exercise 6

What is the remote for this local repository?

Git has created a new directory with the chosen name. First, move to it and then check the remote.

BASH 

cd git-example-friend/
git remote -v

Using branches

If you are using GitHub as a remote storage for your code and you are the only contributor, you will most likely push your changes to the main branch.

However, when you contribute to other remote repositories, you would always use a branch of your own which can then be merged to the remote repo main branch.

In the git-example-friend repository, create a new branch:

git checkout -b [yourname]-new-feature

You are free to choose a name, but it is useful agree on some rules or practices in a project with several contributors. A common choice is something with your name and something that indicates what this branch is for.

You can check the branch with

git branch

The star indicates in which branch you are.

Exercise 7

Create a new file in the repository, add and commit it locally and then push it to the remote repository.

Note: instead of main in git push origin main, you will now use your new branch name.

Create a file

BASH 

echo sometext > yourname-file.txt

Check the status, add, commit and push:

BASH 

git status
git add .
git commit -m "[yourname]: some descriptive message"
git push origin [yourname]-new-feature

Did you get an error? Ask your friend to invite you as a collaborator in the repository from Settings -> Collaborators and teams -> Add people.

In the GitHub Web UI of the repository, a message about recent pushes has now appeared. You can now open a pull request from the new branch to the main branch.

Click on Compare and pull.

Describe the pull request in the text field.

Then click on Pull.

You can then explore the changes, and add some discussion.

There is an option to review changes and approve them. It can be set as obligatory in the repository settings.

Usually, the owner of the project merges the pull request.

Once the pull request is merged, remember to update your local repository. Do the following:

BASH 

git checkout master
git pull

Optional exercise 8

Try this for fun:

Create a Git repository on your university account (or lxplus at CERN if you have an account), add and commit some files in it.

Clone the repository to your laptop: instead of git@github.com:/<repository>.git, use youraccount@domain:/full/directory/path in git clone.

Check the remote repository address on your laptop.

Try if you can push changes from your laptop to the remote on your university account.

Note that this not necessarily what you would ever do, but it illustrates that Git is completely independent from GitHub or GitLab.

Note also that Git does not allow to push to a branch that is checked out in the remote repository. You will have to push to another branch.

Key Points

  • You can turn any directory to a versioned code repository with Git.
  • You can upload the content of a local repository to a remote repository such as GitHub.
  • You can contribute to other Git repositories.

Content from Store and share your code

Last updated on 2024-06-28 | Edit this page

Overview

Questions

  • How to upload your code to GitHub?
  • What information to add to make the code reusable?
  • How to contribute to someone’s code?
  • How other people can contribute to your code?

Objectives

  • Upload a Pythia example to a GitHub repository
  • Make sure that it contains all necessary information for its use
  • Test someone’s code and propose improvements
  • Contribute to the code through pull requests
  • Review and approve pull requests to your code

Create a GitHub repository for your Pythia code

During the Pythia sessions, you have exercised with different examples. Upload one of them to GitHub.

Prepare a local repository

Create a local Git repository under your Pythia working directory for one of the examples.

Make sure that the directory has all necessary files to run the example. Make a separate directory without other file if needed. In general, it is a good practice to structure it so that it has subdirectoris for code, inputs and outputs:

$ tree example_dir/
example_dir/
├── code
├── inputs
└── outputs

However, for the Pythia examples, the Makefile is written so that it expects the code files to be at the same level with it. So leave it flat for now.

Move to the directory and initialize it with

BASH 

git init

Test that everything works, i.e compile and run the code.

Remember to compile and run the code in the Pythia container. Start it from the working repository with

BASH 

docker run -v $PWD:/host -w /host -it --rm hepstore/rivet-pythia

Exclude files with .gitignore

Before committing files to the repository, think what files you would like to exclude. Create a .gitignore file with the names of the files that you do not intend to upload.

See .gitignore example files in https://github.com/github/gitignore In our case, you will probably leave out the executable file. If it is called main01 , the contents of the .gitignore file would be

main01

Note that the file starting with dot (.) are not visible with the usual ls commands, use ls -a to see them.

Commit the files

Add the files you want to version and commit them.

Check the status:

BASH 

git status

Note that the executable file defined in the .gitignore file does not appear in the list. Git ignores it as the name says.

Always make sure to add only the files that you want to commit and in case some unwanted file appear in the list of Untracked files, add them to .gitignore (or remove if you do not need them).

Add and commit:

BASH 

git add .
git commit -m "First commit"

Upload the local repository to GitHub

Create a GitHub repository and push your files there.

Go to your GitHub area (https://github.com/[yourgithubname]), choose the “Repositories” tab and click on New.

Choose a repository name, select Public and leave other options as they are. This will create the repository and generate an instruction page, and you can copy the commands under the title “…or push an existing repository from the command line”.

BASH 

git remote add origin git@github.com:[yourgithubname]/[yourreponame].git
git branch -M main
git push -u origin main

Note that the SSH key connected to GitHub is in your local file system, and it is not in the directory that is shared with the container. Therefore, you will not be able to push to your GitHub repository from the container. Do it from your local shell.

Add instructions

Add instructions to your repository so that other people know what your code does and how to use it. Write them in README.md and push them to the GitHub repository.

Good instructions should contain

a brief description of the code

description of the running environment

description of the input parameters

instructions to compile and run

description of the expected output

Write them in a new file called README.md.

Check status:

BASH 

git status

Add and commit:

BASH 

git add .
git commit -m "Add README"

Push to the remote repository:

BASH 

git push origin main

Run someone’s code

Clone someone’s repository and run their code

Ask other participant the address of their GitHub repository and clone it locally.

Note: first move up from your Git repository. Do not nest Git repositories.

Follow their instructions to run the code.

Move to your working area, and use git clone. Copy the repository address from the green Code dropdown menu (ssh tab).

If their repository name is same as yours, give it another name locally:

BASH 

git clone git@github.com:[someoneelse]/[repositoryname].git [localrepositoryname]

Follow the instructions in the README to understand the code, and to compile and run it. Is the output as expected?

Contribute to someone’s code

Open a GitHub issue to suggest improvements

Suggest an improvemnt to the code or to instructions. Open a GitHub issue in the repository.

Code to the GitHub repository of the code you cloned and find the “Issues” tab. Click on New issue:

Write a descriptive title.

In the issue text, always explain

what you observed

what you expect

how to reproduce (if it is a code issue)

Be respectful and polite.

To contribute, there are two approaches:

Callout

Fork and pull

In the fork and pull model, anyone can fork an existing repository and push changes to their personal fork. You do not need permission to the source repository to push to a user-owned fork. The changes can be pulled into the source repository by the project maintainer. When you open a pull request proposing changes from your user-owned fork to a branch in the source (upstream) repository, you can allow anyone with push access to the upstream repository to make changes to your pull request. This model is popular with open source projects as it reduces the amount of friction for new contributors and allows people to work independently without upfront coordination.

Callout

Shared repository

In the shared repository model, collaborators are granted push access to a single shared repository and topic branches are created when changes need to be made. Pull requests are useful in this model as they initiate code review and general discussion about a set of changes before the changes are merged into the main development branch. This model is more prevalent with small teams and organizations collaborating on private projects.

Provide a fix to the issue you described

As the code is in someone’s personal GitHub area, fork and pull approach seems appropriate. You do not need to be added as a collaborator to the repository to propose changes. It is up to them to accept your changes or not.

Fork the code to your own GitHub area in the GitHub Web UI. Change the remote of your existing Git repository.

In the GitHub Web UI, find the “Fork” button in the GitHub repository to which you want to contribute. Create a fork.

Then connect your local repository to that for:

Either change the origin of your existing local repository (cloned directly from its original area) and check the eventual updates

BASH 

git remote rm origin
git remote add git@github.com:[yourgithubname]/[repositoryname].git
git pull origin main

or remove the existing local repository (rm -rf) and clone it again from your fork.

Then fix the issue in your local repository.

If it is in the code, compile and run (remember, in the container!!)

Check status:

BASH 

git status

Add and commit:

BASH 

git add .
git commit -m "describe the change"

Push to the remote repository which is now your fork:

BASH 

git push origin main

In the GitHub Web UI of your forked repository, will find a message about number of commits ahead.

Click on Contribute and click on the green button “Open pull request”.

Check that the base repository is what you want.

Modify the title if needed and a description.

If you add closes #[issuenumber] in the title or in the description, the issue will get closed automatically once once the pull request is merged. You can find the issue number in the in the list of issues in the GitHub Web UI.

Click on the green button “Create pull request”.

Accept a pull request

The pull request appears in the repository to which you contributed.

Maybe someone has forked your repository and proposes a pull request.

Review and accept the pull request

In the GitHub Web UI of the repository, find the list of pull requests.

Choose the pull request.

In the “Files changed” tab, you can see the changes.

You can open a comment for a specific line in the changes by clicking on + at the start of the line.

Find the green “Review changes” button on the right. You can comment, and as the owner of the repository, approve or request changes.

In the “Conversation” tab, you can “Merge pull request” and “Confirm merge”.

Key Points

  • It is easy to store and share your code through a GitHub repository.
  • Clear instructions make it possible for other people to run your code.
  • You can contribute to other repositories from your own fork, or directly to the repository if you are added as a collaborator.
  • Other people can contribute to your repository through pull requests from their own fork.