How To work with github

Creating your own fork

First of all, we need to know that in a collective project we are all in the same page. Thus, there is a common repository everyone has access to. That's, once again: https://github.com/SedFoam/sedfoam.

To avoid unwanted modifications, irreversible mistakes, or untested new features, direct code changes in the common repository are not allowed. Instead, a maintainer needs to review and accept the commits from any developer who wants to contribute to the project.

If you want to collaborate and create new content for SedFoam you should develop your changes in a GitHub fork. A fork is a copy of a repository which links the original repository (https://github.com/SedFoam/sedfoam) and your personal copy. Forks allow you to edit the contents of your forked repository without impacting the original repository.

In order to create your SedFoam fork go to https://github.com/SedFoam/sedfoam and click the Fork button. Currently, your fork only exists on GitHub. To be able to work on the project, you need to clone it to your computer:

git clone --recurse-submodules https://github.com/USERNAME/sedfoam.git

Previous URL is found in your SedFoam fork.

It is strongly recommended to keep your fork up to date by tracking the upstream repository that you forked. To do so, you need to add a remote:

# Add 'upstream' repo to list of remotes
git remote add upstream https://github.com/SedFoam/sedfoam.git

# Verify the new remote named 'upstream'
git remote -v

It is good practice to periodically update your fork with the latest version of the usptream repository. First, fetch the upstream repository's branches and latest commits to bring them into your repository:

# Fetch from upstream remote
git fetch upstream

# View all branches, including those from upstream
git branch -va

At this point you need to make sure your branch (we'll discuss them later) is the develop branch:

# Checkout the develop branch
git checkout develop

Optionally, you can propmt the changes before merging executing:

git diff develop..origin/develop 

Then you can merge the upstream repository's develop branch:

# Merge upstream
git merge upstream/develop

Now, your local develop branch is up-to-date!

Alternatively, you can update you branch with the following command:

git pull --rebase upstream develop

git pull is simply shortcut to run a git fetch and then a git merge

Create branches

Branching is the way to work on several versions of a repository at the same time. By default your repository has one branch named master (latest official release), and one branch named develop (with the latest developments). Whenever you begin to develop a new feature, it's important to create a new branch (a copy of the develop branch). It is common to use a certain branch for each new feature. Experimenting in new branches is not only a good practice, but it also helps you keep the changes organized and separated from the develop branch. To create a new branch, first, you want to make sure you are in the develop branch:

git checkout develop

Then, a new branch named Newfeature (you can give the name you want) is created typing:

git branch Newfeature

We have, so far, created a copy of the develop branch called Newfeature. To start working in the new branch you should execute the following command:

git checkout Newfeature

Cloning a specific branch

In some case, specially if you are developing a new feature with more people, you might be interested in cloning a specific branch. In order to clone a specific branch you should execute “git clone -b” and specify the branch you want to clone:

git clone -b branchToBeCloned https://github.com/USERNAME/sedfoam.git

Make and commit changes

Every time you make important changes in your local repository, it's worth uploading the modifications on your GitHub branch. Keeping your changes remotely on GitHub will store your modifications in a safe place and it will be accessible from anywhere, so you don't need to be in your computer to work in your new feature. Additionally, commit messages will capture the history of your changes, so other contributors can see and understand your work. First of all, you can run:

git status

to display the state of the repository and see the tracked and untracked files. Changes not staged and untracked files can be easily included with:

git add <File Name>

In order to add changes from all tracked and untracked file you can execute:

git add -A

In case you want to delete some files:

git rm <File Name>

In case you want to restore some files in the working tree:

git restore <File Name>

Before committing any files it is a good practice to inspect the diff output to make sure your changes are correctly introduced:

git diff <File Name>

Then, files staged in your local repository need to be committed:

git commit -m "Write a message describing the new feature you introduce"

Finally, to upload your changes to your remote branch on GitHub, you should use:

git push origin Newfeature

After executing the last command, you pushed the changes in your local repository to the remote GitHub repository (called origin), both named Newfeature.

Open a Pull Request

Whenever you consider the new feature is ready, you can propose your changes and request someone to review your work. The maintainer will carefully study the new features and, eventually, if they are sound, he/she/they will pull in your contribution and merge it into the develop branch.

The easiest way to carry out a pull requests is to go to your GitHub fork and click the pull request button on the main repository page. Then click on the New pull request green button.

The maintainer will decide to merge/deny or comment your changes. If the maintainer suggests some modifications before merging, you can simply push these changes into your fork and the pull request will be updated automatically.

How to delete a branch

Using the following command deletes a specific local branch:

 git branch -d  NewFeature

If you also want to delete a remote branch, then:

 git push origin --delete  NewFeature

Finally,

 git fetch --prune

will clean the outdated branches. It will connect to a shared remote repository remote and fetch all remote branch reference. It will then delete remote reference that are no longer in use on the remote repository.

How to fix the conflicts

A common scenario one can easily come across is to try to push some changes in a branch that has been already modified by others. Once you want to get changes done by others:

git pull --rebase upstream develop #Pull new updates from the upstream to your branch.
git push  #Merge changes from upstream into your gitlab repo (origin)

Then, an error will pop up. A possible way to keep on and update your branch consist in preserving your changes to stash:

git stash #backup and hide changes
git pull --rebase upstream master
git push
git stash pop #restore backed up changes