summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndreas Widen <andreas@harmonicflow.org>2016-02-16 18:17:17 +0100
committerAndreas Widen <andreas@harmonicflow.org>2016-02-16 18:17:17 +0100
commit16bb8f842120be069961b0235eb9b1ed1899ab07 (patch)
tree5249a01a15fb5be55d8f9e508fb52b6e2de47db9
parent2563c85900e661271abbac3bdad04ec39afdbbe5 (diff)
downloadHarmonicFlowOrgWeb-16bb8f842120be069961b0235eb9b1ed1899ab07.tar.xz
HarmonicFlowOrgWeb-16bb8f842120be069961b0235eb9b1ed1899ab07.zip
New blog post: Git Basic Usage.
Signed-off-by: Andreas Widen <andreas@harmonicflow.org>
-rw-r--r--blog/data/2016-02-16-17:37:18-git-basic-usage.txt300
1 files changed, 300 insertions, 0 deletions
diff --git a/blog/data/2016-02-16-17:37:18-git-basic-usage.txt b/blog/data/2016-02-16-17:37:18-git-basic-usage.txt
new file mode 100644
index 0000000..497f378
--- /dev/null
+++ b/blog/data/2016-02-16-17:37:18-git-basic-usage.txt
@@ -0,0 +1,300 @@
+Title: Git Basic Usage
+Tags: git-tutorial, git-basic-usage
+Date: 2016-02-16 17:37:18
+Format: markdown
+
+## 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](/blog/git_basic_setup.php) for a tutorial on how to
+setup Git.
+__CUT__
+
+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](/blog/git_basic_setup.php) 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:
+<pre>
+$ git clone https://git.harmonicflow.org/repos/HarmonicFlowFramework.git
+</pre>
+
+Repository will be cloned into current folder, if you want it elsewhere use
+the following command:
+
+<pre>
+$ git clone https://git.harmonicflow.org/repos/HarmonicFlowFramework.git ~/development/libhffwk
+</pre>
+
+## 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:
+<pre>
+$ git remote add upstream ssh://user@example.org/home/git/repos/HarmonicFlowFramework.git
+</pre>
+
+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:
+<pre>
+$ git remote remove upstream
+</pre>
+
+If you want to see where each remote is pointing, use the following
+command:
+
+<pre>
+$ git remote -v
+</pre>
+
+## 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:
+
+<pre>
+$ git branch
+</pre>
+
+To create a new branch, naming it whatever you want, use the following
+command:
+
+<pre>
+$ git branch branch_name
+</pre>
+
+To create a new branch, naming it whatever you want, and switch to it, use
+the following command:
+
+<pre>
+$ git checkout -b branch_name
+</pre>
+
+To delete a branch, use the following command:
+
+<pre>
+$ git branch -D branch_name
+</pre>
+
+To switch to a branch, making it the currently active branch, use the
+following command:
+
+<pre>
+$ git checkout branch_name
+</pre>
+
+To see available tags, use the following command:
+
+<pre>
+$ git tag -l
+</pre>
+
+To switch to a new branch based on a specific tag, use the following
+command:
+
+<pre>
+$ git checkout -b branch_name tag_name
+</pre>
+
+Rebasing is a common way to integrate upstream changes into your local
+repository.
+
+<pre>
+$ git rebase development
+</pre>
+
+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.
+
+<pre>
+$ git rebase -i development
+</pre>
+
+As an example, in order to return to your master branch, use the
+following command:
+
+<pre>
+$ git checkout master
+</pre>
+
+## 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:
+
+<pre>
+$ git checkout development
+</pre>
+
+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**.
+
+<pre>
+$ git add modified_file1 modified_file2 new_file1
+</pre>
+
+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:
+
+<pre>
+$ git add .
+</pre>
+
+## 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.
+
+<pre>
+$ git commit -s
+</pre>
+
+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.
+
+<pre>
+$ git commit --amend
+</pre>
+
+## 8. Push to online repository
+
+Push the snapshot to your online repository.
+
+<pre>
+$ git push upstream development
+</pre>
+
+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:<br>
+[http://gitref.org/index.html](http://gitref.org/index.html)
+
+For the most direct and complete information on each command:<br>
+[http://www.kernel.org/pub//software/scm/git/docs/](http://www.kernel.org/pub//software/scm/git/docs/)
+
+Amazing and simple tutorial that teaches you everything you need to know
+about using Git:<br>
+[http://rogerdudler.github.com/git-guide/](http://rogerdudler.github.com/git-guide/)
+
+Download the 'Git cheatsheet' and keep it handy:<br>
+[http://rogerdudler.github.com/git-guide/files/git_cheat_sheet.pdf](http://rogerdudler.github.com/git-guide/files/git_cheat_sheet.pdf)
+
+See [Git Basic Setup](/blog/git_basic_setup.php) for a tutorial on how to
+setup Git.
+
+See [How to submit a patch](/blog/how_to_submit_a_patch.php) for a tutorial
+on how to submit a patch using Git.