Hello there,

It is true that there are hundreds if not thousands of tutorials and explanations online about virtually any issue; this page does not intent to be yet another tutorial whatsoever. So, why writing it? Firstly, it is a track of doubts, difficulties and curiosities we have faced while working with GitHub; how we solve them and, above all, a summary of what we have learnt. It is quite common to fall on the same doubt or error twice, having things catalogued here will speed up solving future repetitive problems and, hopefully, help others too. And, secondly, because we really think each person as can give a special touch to anything she/he does and different touches reach different people, so here’s our little different touch to the matter. ;-)

We are writing this guide to help other people to get introduced to the GitHub workflow. Explanations are simple yet rich in the core concepts so that newcomers never get lost in the complexity of the Git clone/pull/push/commit/checkout/branch/O.O workflow. Don’t get scared! Things are easy to understand when you know where you actually are! :-)

May be we can call this initiative a GitHub for dummies?

Find bellow a list of links to the written articles. More articles will be on the way, hopefully, as time availability allows it ;-)

A list of some useful webs that explain GitHub:

• git

Blog Posts:

Starting a project on GitHub

Pushing your updates to the repository

Written ideas that have to be organised:

Branches and development

Creating a branch and pushing it to the repository

The master branch contains the stable working version. It is a very good practice to create a new working branch every time you desire to implement a new feature, or correct the code. That means your work will evolve over that branch without conflicting with the master.

A possible stackoverflow explanation can be found here. There is also a quick explanation on the official try.git tutorial.

Here’s how we do it:

shows the current available branches:

git branch

creates a new branch:

git branch <new_branch_name>

changes to that branch:

git checkout <new_branch_name>

from here start making changes :-)

Now, if you want to commit and push changes on that branch to the branch in the online repository:

git add <files>
git commit -m <you commit message>
git push origin <new_branch_name>

If you are going to work for a considerable amount of pushes in the <new_branch_name> you can also do:

git push -u origin <new_branch_name>

and the -u option will remember git that you want to push to the <new_branch_name>, and for that moment on, just do git push to push to the new working branch. Nevertheless, remember to later:

git push -u origin master

when you want to revert pushing to master again :-)

Moving between branches

Happen this week, I was working on a branch which I wanted to abandon at the end and change back to the master branch. Just typing:

git checkout master

will revert your local files to how they are in the master. From this point you can pull to get updated with the server.

If you want to go back to the branch you were working before, just:

git checkout <branch>

Adding a server branch to your local folder

Imagine there’s a branch on the repository that it is not synchronised on your local folder and you want to work on it. To download it to your local folder [ref]:

git checkout -t origin/<branch>

Pulling from server when you are on branch

Are you working on a branch and you want to pull from server and you are afraid? We also were… No worries!

git pull

will pull from server the changes only on your current working branch. In the case bellow, working on devel1 and pulling:

12:49 hello-world] git pull
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/joaomcteixeira/hello-world
 aa9aef0..50f0c0e master -> origin/master
Already up-to-date.
12:49 hello-world] git branch
* devel1
 master
12:49 hello-world]

Notice aa9aef0..50f0c0e master -> origin/master, means there’s new commits on master that you haven’t pulled. It just tells you that those commits are there, for now no need for worries.

Merging the branch to master

You have finished all your improvements and bug fixes in the development branch. You want to merge them to master. This is a possible workflow [reference on Stackoverflow]:

1. push the <branch> to the server
2. checkout master
3. pull master from server.
4. checkout <branch>
5. merge master with <branch>
6. resolve incompatibilities
7. checkout master
8. repull if you wish
9. merge <branch> with master (incompatibilities should have been solved on 6.)
10. commit and push

Confusing? Not so, the idea is to first merge the master with the development branch>and then transfer everything to master only after incompatibilities are solved. On the command line it would be:

git checkout master
git pull
git checkout <branch>
git merge master
(solve incompatibilities and commit/push them)
(commit and push <branch>)
git pull (to see if there were extra changes meanwhile)
git checkout master
git merge --no-ff <branch>
git push

Do NOT forget the –no-ff flag ! ;-)

This process can be repeated as much as necessary until <branch> can be merge to master with version conflicts solved. Here’s an example picture of how the project evolved.

There were two merges of master into devel2 branch followed by the respective version conflict corrections prior to merge devel2 into master.

A branch out of a branch

If you are working on <branch1> and from this you want to branch out to <branch 1.1> just create <branch 1.1> while on <branch1>. Push/pull/merge/commit between <branch1> and <branch 1.1> work the same way as described before for <branch>/master, where in this case <branch1> is the «master«.

Deleting a local branch

You can delete a local branch with [ref]:

git branch -d <local_branch>

And you can always retrieve it from the server later with

git checkout -t origin/<branch>

Pushing prior to pulling

As far as we know, this is not permitted. The server identifies that the version of your last commit is outdated compared to the version in the server and creates a version incompatibility issue. You must pull from server first. Git will try to merge both changes (yours and those from server) and, if that is not possible, you should solve the incompatibilities manually and then commit and push.

12:58 hello-world] git push
To https://github.com/joaomcteixeira/hello-world
 ! [rejected] devel1 -> devel1 (fetch first)
error: failed to push some refs to 'https://github.com/joaomcteixeira/hello-world'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
12:58 hello-world]

Here is represented an example with version merging incompatibilities.

12:58 hello-world] git pull
remote: Counting objects: 3, done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0
Unpacking objects: 100% (3/3), done.
From https://github.com/joaomcteixeira/hello-world
 c5e300a..1c93027 devel1 -> origin/devel1
Auto-merging red.txt
CONFLICT (content): Merge conflict in red.txt
Automatic merge failed; fix conflicts and then commit the result.
13:01 hello-world]

if you status

13:01 hello-world] git status
On branch devel1
Your branch and 'origin/devel1' have diverged,
and have 1 and 1 different commits each, respectively.  
    (use "git pull" to merge the remote branch into yours)

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
 
      both modified:   red.txt

no changes added to commit (use "git add" and/or "git commit -a")

notice both modified: red.txt

version differences will be displayed as this in red.txt:

<<<<<<< HEAD
again push and pull -> from main
=======
again push and pull -> sending from trials
>>>>>>> 1c93027477af585fe1b3612cd5e4f1cafea88ee0

Now you can work on the version incompatibilities and then commit/push.

When version incompatibilities occur, you will see in the Network Graph that the workflow as derived to what looks like a «temporary new branch» that is created until merge is solved.

What’s the buzz about Fork’ing?

What is the meaning of forking (fork) someone’s project on Git? You fork someone’s project when you want to contribute to that project (without the need for the owner to give you internal access to the original repository).

The workflow of forking can be described as follows (ref):

1. Fork the desired repository to your account
2. clone your forked repo to a local folder
3. keep updated with the original by adding the original remote.
4. create a branch and develop it.
5. merge the master/branch in your repo
6. pull request :-)