---
title: GIT handbook
tags: handbook,git,WIP
---

GIT handbook
===

This handbook aims to provide only the essential piece of knowledge for a developer to functionally use git right away.

The following are content of this handbook:
- [Basic Git](#basic-git)
- [Committing](#committing)
- [Branching](#branching)
- [Fast Forwarding](#fast-forwarding)
- [Merging](#merging)
- [Rebasing](#rebasing)
- [Pull Request](#pull-request)
- [Example Git Process](#example)
- [Glossary of Terms](#glossary)

# Basic Git <a name="basic-git"></a>
Git is a **version control system** which would allow you to track the history of changes as people and teams collaborate on projects together.

Essentially Git allows you to find out and review the following:
* Which changes were made?
* Who made the changes?
* When were the changes made?
* Why were changes needed?

To use Git, developers use specific commands to copy, create, change, and combine code.

#### Here are some common commands for using Git:

* `git init`
initializes a local brand new Git repository and begins tracking an existing directory.
* `git clone`
creates a local copy of a repository that already exists remotely.
* `git add`
stages a change. Git tracks changes to a developer’s codebase, but it’s necessary to stage and take a snapshot of the changes to include them in the project’s history. This command performs staging, the first part of that two-step process. Any changes that are staged will become a part of the next snapshot and a part of the project’s history. Staging and committing separately gives developers complete control over the history of their project without changing how they code and work.
* `git commit`
saves the snapshot to the project history and completes the change-tracking process. In short, a commit functions like taking a photo. Anything that’s been staged with git add will become a part of the snapshot with git commit.
* `git status`
shows the status of changes as untracked, modified, or staged.
* `git branch`
shows the branches being worked on locally.
* `git merge`
merges lines of development together. This command is typically used to combine changes made on two distinct branches.
* `git pull`
updates the local line of development with updates from its remote counterpart. Developers use this command if a teammate has made commits to a branch on a remote, and they would like to reflect those changes in their local environment.
* `git push`
updates the remote repository with any commits made locally to a branch.

Learn more commands from the official docs on git [commands](https://git-scm.com/docs/git#_git_commands)

#### git configuration
Before git allows you to commit it would ask you to configure the following:
- username
`git config --global user.name "your name"`
- email
`git config --global user.email "your email"`

# Committing <a name="committing"></a>

* A commit message should be short
* Write commit message in the imperative form
- Correct: **"Fix"**, **"Add"**, **"Remove"**, **"Update"**
- Wrong: "Fixed", "Added", "Removing", "Updated"
**If you notice imperative forms are shorter in length.**
* If the commit refers to an issue, add this information to the commit message body
* Always leave the second line blank
* If commit can be meaningfully break into multiple commits or issues, break it before pushing
* If multiple commits are the same, do Squash/Fixup before pushing

Example commit message without body
`git commit -m "Fix typo in introduction to user guide [issue#34]"`

1 | Fix typo in introduction to user guide [issue#34]

Example commit message with body
`git commit`

1 | Fix Issue#34
2 |
3 | Remove trailing spaces
4 | Update sentences to correct grammar
5 | Add h1 tags to title
6 | reference: http://bug-reportsheet.com#line34

Technically, You can think of commit as a way of communicating with the other developers in the project

{%hackmd 4ktkuUhhSuafXzavIeIq5A %}

# Fast Forwarding <a name="fast-forwarding"></a>
{%hackmd C6em00QGSZCjEyl1lIUYUg %}

# Merging <a name="merging"></a>
{%hackmd k_Vr8bq-TLGvXHuaUViHxA %}

# Rebasing <a name="rebasing"></a>
{%hackmd dIQwIoHBSHaO9YegrdbMcw %}

# Pull Request <a name="pull-request"></a>
{%hackmd mgOEzKYpS563zTvezg7f4w %}

# Example of Usual Git Process

0. Task is assigned to you
1. Create local branch for the task [ for branch naming please refer to [branching](#branching) ]
2. Create or Update file(s)
3. Add changes onto staging
- `$git add "enter full path file path here" `
- Alternatively you can do wildcards i.e `git add ./folder/*.php` this add all files ending with .php
4. When a single change or group of changes could mean something descriptive change then create a commit
- `git commit -m "Enter commit message here"`
- Commit message describes what the changes is.
- when creating commit message, always start with verb of what will change when commit is applied
- "Add initial files for partner-application"
- "Remove extra 's' on menu service"
- "Update links to partner-application"
5. Repeat 1-3 whenever there are changes to be made for the task to be finish.
6. Test, Check and Review your updates
* Ensure the commit does not include non-related files in the commit message.
* Squash commits before pushing ( i.e commit #1 "Fix error in command", commit #2 "Fix error in command" must be squash into 1 commit as they are same fix )
* Ensure no syntax or compilation error in your changes
7. Push updates to your remote branch
8. Create Pull-request

Now the reviewer or other co-developers involved can easily understand without looking inside files changes on what the Pull-request would update by just looking at the commits initially.

Now if we use the sample commits above from #4
1. "Add initial files for partner-application"
2. "Remove extra 's' on menu service"
3. "Update links to partner-application"

in #1 All reviewers would see are files added (1 php, 4 css, 1 svg and 2 png)
in #2 Without looking inside the file reviewer can easily guess that you're just removing "s"
in #3. similar with #2

`[Note: This is a sample git process only, you don't actually have to do the same commit specified above like #2]`

Now say you want to undo commit #2 "without making changes to the file or do another commit". because changes are divided into multiple commits we can easily just do `git rebase -i <commit>` and delete the commit line.

if we don't divide the changes into multiple commits you would have to update that specific file and do another commmit or in a scenario where you want to undo changes reverting that commit affects #1 and #3.

the same scenario for branching features update or fixes . If updates are not done by branching, there would be more work in reverting/undoing the applied feature

# Glossary of terms
The terms listed here are the commonly used terms.

- **origin**
Refers to the shorthand name for the remote repository that a project was originally cloned from
- **local**
Refers to your local git residing in your local machine
- **remote**
Refers to the git remote repository i.e Github, Bitbucket, Gitlab
- **Gitflow**
is a branch model and release management workflow that helps developers keep track of features, htofixes and releases in bigger scale software projects.
- **Pull Request / PR**
Essentially means that the merge between branches is done on the remote repository site, in usual circumstances PR requires reviewer to approve the changes before a merge is done.
- **HEAD**
The current branch and the latest commit it is pointing onto
- **upstream branch**
The default branch that is merged into the branch, If the upstream branch of A is origin/B sometimes we say "A is tracking origin/B".
- **commit**
As a noun: A single point in the Git history; the entire history of a project is represented as a set of interrelated commits.
- **push**
Push means to upload your commits to the remote repository
- **pull**
Pulling a branch means to fetch it and merge it
- **fetch**
Fetching a branch means to get the branch’s head ref from a remote repository,

For more info you may refer to the official [git glossary](https://git-scm.com/docs/gitglossary)

# Other Reads
- [commit rules](/-Hhdh-KTQtCNGZY3YdqJPw)
- [git ignore configuration](/PYdlVYnWRXylLc8Datrp0w)
- [branch rules](/4ktkuUhhSuafXzavIeIq5A)