Skip to content

Git Basic

Jump to bottom Edit New page
chantisnake edited this page Jul 17, 2017 · 10 revisions

This is tutorial is to teach you about the basic concepts in Git.

Tutorial

Track your code changes

Intros

When you have a code base, you will constantly make changes to it: maybe adding a new function, adding documentation to functions, fix a bug, or remove deprecated functions.

Definitions

Commit is like a saving point in games, you can save your changes with a description:

  • File Changed: the file changes you want to track in this commit
  • Commit Message: a message describe your changes

Examples

Let's think of our code as a simple time line, consists of three commits: A, B and C

A ---> B ---> C

Each of them will have Their corresponding File Changes and Commit Message

How to Use

For technical detail about how to commit see [commit on PyCharm].

A good rule of thumb is commit as often as possible, whenever you can describe your changes clearly you need to make a commit.

A good commit will serve the following purpose:

  • It works like a saving point, if current version is messed up, we can always go back.
  • We will know who to blame when something messes up.
  • We can easily visualize what we are doing with our code, because each commit has a message associate with it.

Back up you code into the cloud.

Intros

The cloud, or as we will call it in the future: remote, is very useful to share code with others, to edit code with others and to save your code in a secure place

Git provide us a sync (or push in pycharm) feature to backup our commits into the remote (In our case, the remote server is provided by GitHub).

Definitions

  • remote: The server that stores your code (commits), in our case, GitHub.
  • sync (or push in PyCharm): The operation to sync up your local commits with the remote commits.

Examples

Example 1

This time we will enrich our previous example with a remote line:

remote: A ---> B

local:  A ---> B ---> C ---> D

This time we can see that our local is 2 commits ahead of (has 2 more commits) the remote. When we do sync, our local change got pushed onto the remote:

remote: A ---> B ---> C ---> D

local:  A ---> B ---> C ---> D

you can see that the commits C and commits D gets pushed onto the remote.

Example 2

Let's make our model a little more real.

remote: A ---> B ---> E

local:  A ---> B ---> C ---> D

This time there is one commits E on the remote but not on the local. This picture is a much more realistic view of what happens when your are working with others.

Because you are not the only one that pushes to the remote, therefore it is very likely that there are other codes that your coworker puts on the remote.

What should I do now?!, you have two choices:

  1. panic, run around the lab and annoys English people.
  2. realize that Git will take care of it for you.

Of course, our good friend Git will always prevent us from running around the lab.

When you execute sync, Git will put your commits in place:

remote: A ---> B ---> C ---> D ---> E

local:  A ---> B ---> C ---> D ---> E

How to Use

for technical detail about how to sync, see [push on PyCharm].

We recommend push when possible, which means you push when all of the following criteria match:

  • Internet access. (obviously you cannot push to the remote server if there is no internet)
  • You made an commit. (because sync only syncs commits, therefore your local needs to be at least 1 commit ahead of the remote)

See the code base as branches

Intros

In fact, we have already encountered the idea of branch. In the last section, we have remote and local: they are in fact two branches, because they belongs to the same code base and can be synced together.

Definition

branch is refers to a branch of the code base, deferent branches can be synced together.

Example

Let's start with Example 2 from the previous section.

remote: A ---> B ---> E

local:  A ---> B ---> C ---> D

we can draw it a little more like branch

remote: A ---> B ---> E
                \
local:           ---> C ---> D

Because they both share commit A and commit B, there is no point to draw them twice. Now we can see that, the remote and local are actually branches of a tree.

when we sync the local with the remote, we simply draw this as:

remote (local): A ---> B ---> C ---> D ---> E

Create a new branch and check it out

Intros

We see that remote and local are actually two natural branches, but can we manually create more branches? of course, we can always create new local branches, and sync them to the remote.

After we created our new branch, we probably wanted to work on the new branch (make commits on it). Git provide us a functionality called checkout, to change the file on the disk to the file on the branch.

Definitions

create a branch: create a new branch to keep track of our source code.

check out branch b: change the local code base to branch b

Examples

Let's continue with the example from the previous section, I will reduce some commits for simplicity:

remote: A ---> B
local:  A ---> B

Now I want to create a new branch on the local, called new, notice we are still on the local branch:

remote: A ---> B
local:  A ---> B  <- We Are Here
new:    A ---> B

We need to first checkout to the new branch on local:

remote:    A ---> B
local:     A ---> B
local/new: A ---> B  <- We Are Here

Now, let's just create an commit like we did before (change the notation to branch notation):

remote:       A ---> B

local:        A ---> B
                      \
local/new:             ---> C  <- We are Here

These is all very intuitive. But now we need to checkout back to local:

remote:       A ---> B

local:        A ---> B         <- We are here
                      \
local/new:             ---> C

Now if you look at your code base, you will see all the changes you made in commit C magically disappeared, because you are on local branch. This behavior is what we mean by "changing the code base to branch local".

How to use

For technical detail about how to create a branch, see [Create a branch on Pycharm].

For technical detail about how to checkout a branch, see [Checkout a branch on Pycharm]

Typically a branch is created when you want to do a bug fix or add a new feature (you can regard this as a larger commit). We will talk about how to use branch to manage code even more in the next couple of sections.

Keep your branch up-to-date with others

Intros

Frist, we need to introduce master branch: master is the common name for the default branch in the repository: our local should really name local/master, remote should really name remote/master.

There are different projects uses master branch in different ways, but they all have somethings in common:

  • code in the master needs to be good enough to be trusted
  • commits in the master branch needs to be good enough to be included in the next release.

(Lexos will require everyone to review the code before the code reaches master, see pull request section for more)

Second, we need to know another concept called merge: merge is a functionality that brings the commits from other branch to the current branch.

Typically we will merge mater branch onto our current working branch to make sure we are up-to-date on our current development.

Definitions

Merge: Get all the commits from the other branch onto the current branch.

master Brach: Typically means the default branch. This branch only should contain code that are reviewed and stable. (good criteria would be that all the commits in master should be able to go to the next release)

Example

Let's start small, just subsitute our branch with their correct name:

remote/master: A ---> B

local/master:  A ---> B         
                       \
local/new:              ---> C   <- We are Here

Now, let's suppose other worker has pushed to the remote/master.

remote/master: A ---> B ---> D ---> E

local/master:  A ---> B         
                       \
local/new:              ---> C   <- We are Here

There is two new commits on remote/master: D and E. Now when we merge remote/master, git will get the commit from remote/master to our current branch (local/new)

remote/master: A ---> B ---> D ---> E

local/master:  A ---> B         
                       \
local/new:              ---> C ---> D ---> E   <- We are Here

How to Use

For technical detail about how to merge, see [merge on PyCharm]

Here is two things to watch out for when you merge:

  • You will probably always want to merge with remote/master, not local/master
  • It is always nice to merge as often as possible, but you cannot merge when you have any changes that haven't been commited (haven't been saved).

Get your code to the master

Add a custom footer
Clone this wiki locally