Harmonic Flow Framework

Harmonic Flow Blog

Git Basic Usage

Important Git concepts

Git is a powerful decentralized version control system for collaborating on projects and is something that you need to master if you intend to participate in and keep up to date with the Harmonic Flow Framework (libhffwk) project.

See Git Basic Setup for a tutorial on how to setup Git.

Here are the basic terms you should familiarize yourself with before embarking on your journey.

  • Repository / Repo: This is where the project's source code resides. Git has two repository types: local and remote. The local repo is on your computer for only your direct use. The remote repo is typically elsewhere and for your indirect use. Git is decentralized and supports multiple remote repositories.
  • Clone: Clone operation (git clone) creates the instance of the repository. Clone operation not only checks out the working copy, but it also mirrors the complete repository. Users can perform many operations with this local repository. The only time networking gets involved is when the repository instances are being synchronized (such as when using git push command).
  • Branch: Branches are used to create another line of development. By default, Git has a master branch. Usually, a branch is created to work on a new feature. Once the feature is completed, it is merged back with the master branch and we delete the branch. Every branch is referenced by HEAD, which points to the latest commit in the branch. Whenever you make a commit, HEAD is updated with the latest commit.
  • Remote: A remote is simply an alias pointing to an online repository. It is much easier to work with such aliases than typing in the complete URL of online repositories every single time.
  • Staging area: Whenever you want to update your repository, you first need to add your changes (git add) to your staging area. Modifying files locally will not automatically update your staging area's contents.
  • Tag: Tag assigns a meaningful name with a specific version in the repository. Usually, tags are created for product releases.
  • HEAD: HEAD is a pointer, which always points to the latest commit in the branch. Whenever you make a commit, HEAD is updated with the latest commit.

Important Git commands

  • git status: Show the working tree status. This is useful when you want to check what's modified locally.
  • git add: Whenever you modify a file in your local repository or create a new file, that file will appear as unstaged. Calling git add allows you to specify files to be added to your staging area.
  • git commit: A commit records a snapshot of your staging area, making it ready to be pushed to an online repository.
  • git push: Push operation copies changes from a local repository instance to a remote one. This is used to store the changes permanently into the Git repository.
  • git pull: Pull operation copies the changes from a remote repository instance to a local one. The pull operation is used for synchronization between two repository instances.
  • git fetch: Download the current state (containing updated and newly created branches, tags etc) of an online repository without modifying your local repository. It places its results in .git/FETCH_HEAD. Use git fetch --all to include all remotes.
  • git merge: Merge the modifications of another branch into the current working branch.
  • git rebase: Rebasing is a common way to integrate upstream changes into your local repository.

Step by Step: From cloning the repo to pushing your first changes

1. Basic set up

See Git Basic Setup for a tutorial on how to setup Git.

2. Clone the repo

Now that your username and email are configured as minimum, it is time to clone the repository.

Open a terminal and enter the following command:

$ git clone https://git.harmonicflow.org/repos/HarmonicFlowFramework.git

Repository will be cloned into current folder, if you want it elsewhere use the following command:

$ git clone https://git.harmonicflow.org/repos/HarmonicFlowFramework.git ~/development/libhffwk

3. Setting up Remotes

When you first clone a repository, git will automatically create a remote named 'origin' for you.

If you want to store your changes elsewhere it's recommended to setup remotes.

Open a terminal and enter the following command:

$ git remote add upstream ssh://user@example.org/home/git/repos/HarmonicFlowFramework.git

This will add a new remote called 'upstream' which points to your preferred location using ssh method.

If you want to remove a remote, use the following command:

$ git remote remove upstream

If you want to see where each remote is pointing, use the following command:

$ git remote -v

4. Managing Branches

Making changes directly to your master branch is a bad idea. You should always have a working branch to try out your modifications on.

To list the available branches for your current project, use the following command:

$ git branch

To create a new branch, naming it whatever you want, use the following command:

$ git branch branch_name

To create a new branch, naming it whatever you want, and switch to it, use the following command:

$ git checkout -b branch_name

To delete a branch, use the following command:

$ git branch -D branch_name

To switch to a branch, making it the currently active branch, use the following command:

$ git checkout branch_name

To see available tags, use the following command:

$ git tag -l

To switch to a new branch based on a specific tag, use the following command:

$ git checkout -b branch_name tag_name

Rebasing is a common way to integrate upstream changes into your local repository.

$ git rebase development

Running git rebase with the -i flag begins an interactive rebasing session. Instead of blindly moving all of the commits to the new base, interactive rebasing gives you the opportunity to alter individual commits in the process. This lets you clean up history by removing, splitting, and altering an existing series of commits.

$ git rebase -i development

As an example, in order to return to your master branch, use the following command:

$ git checkout master

5. Harmonic Flow Framework (libhffwk) branches

Harmonic Flow Framework (libhffwk) uses the two branches master and development.

The master branch is the 'official' one, the stable version that you should use if you want to create a game using the technology.

The development branch is updated much more often, and will feature works in progress, new features, new toys and various tweaks to the engine. Once changes in the development branch are deemed final and tested properly, these changes will be pushed to the master branch.

When you first clone the repository, you will find yourself in the master branch. It's recommended to use the development branch if you would like to send me a patch.

Use the following command to switch to the development branch:

$ git checkout development

At this point, you are ready to start working with Harmonic Flow Framework (libhffwk)!

6. Adding files

Add your new / modified files. You can always see what's modified in your local staging area with git status.

$ git add modified_file1 modified_file2 new_file1

This will add the specified files to your local staging area.

If you do not call git add on a modified file, the local staging area will simply keep the version of the file which existed when it was last added via git add.

You may also use this command to add all modified or new files in your entire project to your staging area:

$ git add .

7. Commiting changes

Commit to take a snapshot of your local staging area. The -s option adds 'Signed-off-by: Your Name youremail@example.org' which is good practice.

$ git commit -s

The git commit --amend command is a convenient way to fix up the most recent commit. It lets you combine staged changes with the previous commit instead of committing it as an entirely new snapshot. Never amend commits that have been pushed to a public repository. Amended commits are actually entirely new commits, and the previous commit is removed from the project history.

$ git commit --amend

8. Push to online repository

Push the snapshot to your online repository.

$ git push upstream development

The above command will push the changes from your currently active branch to your online repository's development branch.

Recommended reading

The Git Reference docs explain everything about Git with really clear examples:
http://gitref.org/index.html

For the most direct and complete information on each command:
http://www.kernel.org/pub//software/scm/git/docs/

Amazing and simple tutorial that teaches you everything you need to know about using Git:
http://rogerdudler.github.com/git-guide/

Download the 'Git cheatsheet' and keep it handy:
http://rogerdudler.github.com/git-guide/files/git_cheat_sheet.pdf

See Git Basic Setup for a tutorial on how to setup Git.

See How to submit a patch for a tutorial on how to submit a patch using Git.

Posted on Tue, 16 Feb 2016
Tags: git-basic-usage, git-tutorial



Comment On This Entry

Submit a comment on this entry.