Abstract

A website for the basics of Git and GitHub-like services.

Preface

The open source community is inclusive and friendly. Contributing to it is always exciting if done in the spirit of improving the community and enjoying oneself.

Knowing the basics of Git and GitHub is the only prerequisite to start contributing and learning them sometimes feels like a daunting task. The aim of this guide is to help anyone get started with open source and keep helping them along their journey.

This project is open source and the repository can be found at github.com/HarshKapadia2/git_basics. Contributions to keep it updated and error-free are appreciated and issues and pull requests are most welcome!

For further questions, please feel free to contact the author, Harsh Kapadia, via OTC, Twitter, LinkedIn or e-mail (contact@harshkapadia.me).

Important

Git and GitHub sessions by the author:
Note One might want to familiarize themselves with some terms before starting, although they will be linked at places where they are required as well.
Note

'main' vs 'master' #1:

General #1

Version Controlling Systems (VCS)

  • In computer software engineering, revision control is any kind of practice that tracks and provides control over changes to source code.

  • As teams design, develop and deploy software, it is common for multiple versions of the same software to be deployed in different sites and for the software’s developers to be working simultaneously on updates.

  • Bugs or features of the software are often only present in certain versions (because of the fixing of some problems and the introduction of others as the program develops). Therefore, for the purposes of locating and fixing bugs, it is vitally important to be able to retrieve and run different versions of the software to determine in which version(s) the problem occurs.

  • It may also be necessary to develop two versions of the software concurrently: for instance, where one version has bugs fixed, but no new features (branch), while the other version is where new features are worked on (trunk).

Types of Version Control Systems (VCS)

Local VCS (LVCS)

  • Local version control system maintains track of files within the local system. This approach is very common and simple. This type is also error prone which means the chances of accidentally writing to the wrong file is higher.

LVCS

Centralized VCS (CVCS)

  • In this approach, all the changes in the files are tracked under the centralized server. The centralized server includes all the information of versioned files, and list of clients that check out files from that central place.

  • Eg: Tortoise SVN

CVCS

Distributed VCS (DVCS)

  • Distributed version control systems come into picture to overcome the drawback of centralized version control system.

  • Clients completely clone the repository including its full history. If any server dies, any of the client repositories can be copied on to the server which help restore the server. Every clone is considered as a full backup of all the data.

  • Eg: Git

DVCS

Git

  • Git is a free and open source distributed version control system (DVCS) and has an emphasis on speed and performance.

  • It is supported by all operating systems.

  • Git is open source software distributed under the terms of the GNU (General Public License).

  • Official website

git --distributed-is-the-new-centralized
— git-scm
https://git-scm.com/

Git-Bash

  • It is a shell, ie, a CLI to use git.

  • Once Git is installed, it can be used with Command Prompt, Powershell, Terminal, Zsh, etc as well. It is not mandatory to use Git Bash.

  • The official website to download Git-Bash is https://git-scm.com/.

Repositories & its types

  • What is a repository (repo)?

  • Types of repos

    • Local repo

    • Remote repo

      • Public repo

      • Private repo

  • Local repo

    • Local repository is the repo on the local machine (eg: laptop).

    • The local repository has exactly the same features and functionality as any other Git repository.

    • So a Git repo on a local machine (eg: your laptop) is the same as a git repo on GitHub (granted GitHub adds additional features, but at its core they’re both Git repos) which is the same as your coworker’s local repo.

    • The local repo is everything in your '.git' directory. Mainly what is seen in the local repo are all of the user’s checkpoints or commits. It is the area that saves everything (so don’t delete it).

    • touch

      • To create a file in the directory to which the bash is pointing.

      • touch <file_name.ext>

      • Eg: touch create_this_file.txt

Note A local repo does not need to have a remote repo.

  • Remote repo

    • Remote repository is the repo on the server.

    • So while most people treat a particular repo as the central repo (the one on GitHub), that’s a process choice, not a Git requirement.

    • A remote repo and local repo connection is handled using the git remote command.

    • It can be of two types

      • Local repo

      • Remote repo

    For more information on remote repos, refer to Repository (repo) section.

Related

Commands

git

Command

git <flags> <options>

Description

Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals.

git - the stupid content tracker
— git-scm
https://git-scm.com/docs/git

Options/Flags

--version

  • Prints the Git suite version that the git program came from.

--help

  • Prints the synopsis and a list of the most commonly used commands.

  • If the flag --all or `-a`is given then all available commands are printed.

git help

Command

git help <options>

Description

Give information about Git or a certain Git command (from the man pages in the Git package itself).

Options/Flags

No option

  • Synopsis of the git command and a list of the most commonly used Git commands are printed on the standard output.

<command_name> or <concept>

  • Any Git command name (eg: commit, add, etc…​) can be entered.

  • A man (manual) page which is included in the Git package will be opened in the browser.

  • Eg: git help add

git config

Command

git config <flags>

Prerequisites

The following terms are required to be understood:

Description

Get and set repository or global options.

Options/Flags

--global

  • Modify Git’s global (system-wide) configuration. These settings affect all Git repositories on a system.

  • Set user’s name: git config --global user.name "<name>"

  • Set user’s e-mail: git config --global user.email "<e-mail_id>"

Note

  • It is mandatory to fill in these two details.

  • Please enter the e-mail ID registered with the concerned GitHub/GitLab/BitBucket account and the full name.

  • This is the name and e-mail ID that will be associated with each commit.

  • The global name and e-mail need to be set just once, ie, when Git is used for the first time ever on a computer (but can be modified if need be).

  • Change default branch name created on running git init command: git config --global init.defaultBranch "<branch_name>"

Tip

'main' vs 'master' #2:

  • 'main' vs 'master' #1

  • This only applies to GitHub repositories.

  • New GitHub repositories have the name of their default branch as 'main' instead of 'master', while the local Git client still uses 'master' as the name of the default branch when initializing repositories.

  • This mismatch in the names of the default branches causes pushes to new remote repositories to fail.

  • To combat this change on GitHub, it would be advisable to change the name of the default branch of the local Git client to 'main' using the command git config --global init.defaultBranch "main".

  • NOTE: Cloned repositories will not be impacted unless the remote repository’s default branch is changed on GitHub after cloning (in which case GitHub will provide commands to rename the local branch on visiting the repository page on GitHub for the first time after the renaming).

  • Change the default editor for committing, rebasing and other Git operations

    • Command: git config --global core.editor "<editor_name>"

    • Some editor options

      • Vim: vim

      • VS Code: code --wait

      • Sublime Text: subl --wait or \"full/path/to/subl.exe\" -w

  • Aliases can also be set using this flag.

--list

  • Lists the configurations of Git.

  • Eg: git config --list

git init

Command

git init

Prerequisites

The following terms are required to be understood:

Description

To initialize a local git repository in the location to which the bash is pointing. A hidden folder .git is created in the directory. None of the commands below will work if there is no local git repo initialized.

Caution If the remote repository is/is going to be located on GitHub, please be aware of the main vs master default branch issue which might cause git push to fail.

Options/Flags

No option

  • Initializes new repo in the current directory.

  • Creates ./.git.

<new_folder_name>

  • Eg: git init <new_folder_name>

  • Initializes a new repo in ./<new_folder_name>.

  • Creates ./<new_folder_name>/.git.

Git local & remote commands chart #1

git add

Command

git add <flags> <file_name.ext> where `ext`stands for the extension of the file.

Prerequisites

The following terms are required to be understood:

Description

To add files to the staging area (refer to picture above).

Options/Flags

<file_name.ext>

  • Adds a single file to the staging area.

  • If file is located in a folder, use directory_name/<file_name.ext>

  • Multiple file names in one command are allowed with a whitespace in between them.

  • Eg: git add dir/dir1_file.txt

*.ext

  • All files with '.ext' extension will be added to the staging area (except for the file names in the .gitignore file).

. (period)

  • Eg: git add .

  • Recursive command to send all untracked and modified files to the staging area (except for the file names in the .gitignore file).

-p or --patch

  • Enables choosing the staging of specific hunks (group of lines/chunks) of files instead of entire files.

  • It presents the diff between the index (staging area) and the working tree file and asks what one wants to do with the change of each hunk.

  • Using this flag makes Git display hunks one by one and bring up command options for every hunk to

    • y (yes): Stage the hunk.

    • n (no): Not stage the hunk.

    • q (quit): Quit the process and not stage the current hunk or the remaining ones. (Hunks in order can be left undecided temporarily as seen in the options below.)

    • a (all): Stage the current hunk all the ones that follow.

    • d (delete): Not stage the current hunk all the ones that follow.

    • g (goto): Go to a particular hunk. (It will display a list with a hunk number to go to a particular hunk if there are more than 1 hunks.)

    • /: Search for a hunk matching the given regex.

    • j: Leave the current hunk undecided and see the next undecided hunk.

    • J: Leave the current hunk undecided and see the next hunk.

    • k: Leave the current hunk undecided and see the previous undecided hunk.

    • K: Leave the current hunk undecided and see the previous hunk.

    • s (split): Split the current hunk into smaller hunks.

    • e (edit): Manually edit the current hunk in an editor.

    • ?: Print help.

  • Eg: git add -p or git add -p <file_name.ext>

-n .

  • Eg: git add -n .

  • Shows files that will be added, but does not add them.

  • Run other git add commands to actually add files to the staging area.

-u

  • Stages modified and deleted files, without including new (untracked) files.

Related

git status

Commands

git status

Prerequisites

The following terms are required to be understood:

Description

  • Run this command at any time to display the current status of the working directory.

  • This command shows two things:

    • The files in your Working Tree (untracked and modified files)

    • The files in your Staging Area (added files)

Options/Flags

-s or --short

  • Gives a summary of untracked and staged (added) files.

  • Meanings of different symbols

    • ?? implies an untracked file, ie, a file that has never been staged.

    • A implies a newly staged (added) file, ie, a file that is now staged, but has never been staged before.

    • M (red) implies unstaged modifications in a committed file.

    • M (green) implies staged modifications in a committed file (but the new modifications have not been committed yet).

    • AM (green and red respectively) implies new modifications in a newly staged uncommitted file.

    • MM (green and red respectively) implies new modifications in a committed file that has been staged with modifications, without committing the previous changes.

    • D (red) implies the renaming/moving/both (renaming and moving)/deletion of a staged file that has not been staged again.

    • D (green) implies the deletion of a staged file.

    • R (green) implies the renaming/moving/both of a staged file.

    • AD (green and red respectively) implies the renaming/moving/both (renaming and moving)/deletion of a newly staged uncommitted file that has not been staged again.

Note

  • Once a file is renamed, moved or both renamed and moved, it is marked as deleted (red coloured D) by Git and a new untracked file (red coloured ??) is shown in its place when git status -s is run. Once the git add command is run once again, Git realises that the file has been renamed/moved/both and displays a green coloured R when git status -s is run again.

  • If AD is displayed, the newly staged file can have been renamed, moved, both (renamed and moved) or deleted. In the case of renaming, moving or both, the original file gets forgotten in the next staging and the new file is added. In the case of deletion, the file is simply forgotten in the next staging.

git commit

Working of Commit

Command

git commit <flags_&_options>

Prerequisites

The following terms are required to be understood:

Description

A commit is simply a checkpoint telling Git to track all changes that have occurred up to the current point using the last commit as a comparison.

A commit is carried out only if there are files in the staging area, so make sure to run git add before this command.

Every commit has a unique SHA1 associated with it.

Use git log & git show commands to get information on commits.

Important Always pull before committing & pushing.
Tip Commit related changes.
Tip Commit changes frequently. This makes it easier to revert back to older versions to correct mistakes.
Tip Don’t commit half-done or incomplete work.
Commit message/title

  • Every commit has a commit message associated with it which describes the overall change made.

  • Short, crisp and to-the-point commit messages are preferred (<50 characters).

  • Use the imperative, present tense (eg: 'change', not 'changed' or 'changes') in commit messages, to be consistent with generated messages from commands like git merge.

    • Another way to think about commit messages is to write them such that the codebase is being instructed to do something.

    • Eg: git commit -m ":truck: feat: Implement Debouncing for search box"

  • General commit message structure below

  :sparkles: feat: add hat wobble (#26)
  ^--------^ ^---^ ^------------^ ^---^
       |       |         |          |
       |       |         |          +----> PR or issue resolved (if any).
       |       |         |
       |       |         +----> Summary in present tense.
       |       |
       |       +----> Type:- chore, docs, feat, fix, refactor,style, test, etc.
       |
       +----> Emoji:- :tada: :bookmark: :sparkles: :bug: :books: :wrench: :truck:
Important More on types and emojis.

Options/Flags

No option

  • Just running git commit will launch a text editor prompting you for a commit message.

  • After you’ve entered a message, save the file and close the editor using :wq or just save and exit the editor to create the actual commit.

-m "<commit_msg>"

  • Avoids opening a text editor by providing the commit message in the Command Prompt, Terminal, Powershell, etc…​

-m "<commit_message>" -m "<commit_description>"

  • Enter the commit message and commit description if needed.

-a or --all

  • Automatically stages files that have been modified or deleted, but untracked files are not affected.

  • Eg: git commit -a -m "<commit_message>" or git commit -am "<commit_message>"

--amend

  • To change the commit message of the latest commit.

  • This will open a text editor to change the commit message. Once the file is saved and closed, the changes are made.

  • To do it directly from the command line use git commit --amend -m "<new_commit_msg>" -m "<new_commit_description>". (Commit description is optional.)

Note This command will change the commit message of the latest commit only. Refer to git rebase for changing older commit messages.
Caution Any amend command re-writes the history of the repository as it entirely replaces the previous latest commit with the new one, so use this only for commits that are not pushed.
--amend --no-edit

  • Allows amending a commit without having to change the commit message originally/already associated with that commit.

  • One usecase can be that if a user has forgotten to add a few files to the last commit, they can add the files using git add and then amend the last commit with the --no-edit option.

  • Eg: git commit --amend --no-edit

--amend --author="Author Name <author@email.com>"

  • Allows changing the author of the last commit. This does not change the committer of the previous commit.

  • Eg: git commit --amend --author="Harsh Kapadia <contact@harshkapadia.me>

  • If both, the author and the committer of the last commit need to be changed, edit the local or global Git config and then amend the last commit using the git commit --amend --no-edit command.

--allow-empty

  • Allows creating a commit without making any changes.

  • One usecase can be to trigger a CI/CD workflow without making changes to the project.

  • Eg: git commit --allow-empty -m "<commit_message>".

-m "Add only_this_file.ext from all staged files" only_this_file.ext

  • Partially committing staged changes

-s or --signoff

  • Adds Signed-off-by: Author Name <author@email.com> at the end of the commit message.

  • The meaning of a signoff depends on the project being contributed to.

git ls-tree --full-tree -r HEAD

  • This command shows all files within your git repo that it is tracking.

Related

git log

Command

git log <options_&_flags>

Prerequisite

The following terms are required to be understood:

Description

It is a running record of commits. It shows all the commits reachable from the current HEAD (where the next commit will attach).

Implicitly means git log HEAD.

Options/Flags

<commit_SHA1>

  • It will display the details of that commit.

  • For more details of the commit, use git show.

<branch_name>

  • It will display the commit log of that branch.

--oneline

  • Displays the first 7 characters of the SHA1 and the commit message.

--graph

  • It will display commits as a graph.

  • To make it look better, use the --oneline or/and --decorate flags.

  • Eg: git log --graph --oneline --decorate

--stat

  • Displays the files and no. of lines added or removed, in each commit.

'--patch' or '-p -<no_of_commits_to_be_displayed>'

  • Gives details of files changed, specific changes and location of changes in the file.

Related

git rm

Command

git rm <flags> <file_name.ext> where `ext`stands for the extension of the file.

Prerequisite

The following term is required to be understood:

Description

To remove files from the working tree and from the index.

Options/Flags

--cached <file_name.ext>

  • To unstage a particular file (ie, remove file from the staging area).

  • use "" if the file name has spaces in between.

-r --cached .

  • Eg: git rm -r --cached .

  • Recursive command to remove all files from the staging area.

Related
Git local & remote commands chart #2

git pull

Command

git pull <remote_repo_alias> <remote_branch_name>

Eg: git pull origin master

Prerequisites

The following terms are required to be understood:

Description

Pulls (brings) the latest code from the remote repo.

To fetch and download content from a remote repository and immediately update the local repository to match the content.

Difference between git pull and git fetch

  • In simple terms, git pull does a git fetch followed by a git merge.

  • git pull automatically merges commits without letting you review them first. If you don’t closely manage your branches, you may run into frequent conflicts.

Related

git fetch

Command

git fetch <remote_repo_alias> <branch_name>

Prerequisites

The following terms are required to be understood:

Description

On running git fetch, Git gathers any commits from the target branch that do not exist in the current local branch and stores them in the local repository. However, it does not merge them with the current branch (unlike git pull).

This is particularly useful if you need to keep your repository up to date, but are working on something that might break if you update your files.

To integrate the commits into your master branch, you use git merge.

Related

git clone

Command

git clone <remote_repo_url>.git

Eg:

Prerequisites

The following terms are required to be understood:

Description

Clone/copy an entire local or a remote repository into the current directory (to which the CLI is pointing).

A new directory will be created with the name of the repository. cd (change directory) into that directory to start using it.

Options/Flags

No option

  • The default branch of the local or remote repository will be cloned into a new directory with the same name as the repository.

-b <branch_name> or --branch <branch_name>

  • Clone only a specific branch of a remote repo.

  • It is useful to fetch the required branch quickly to fix the issues in a big project.

--depth <depth_number>

  • Shallow clone only upto a certain number of latest commits and history either in a --single-branch (default) or in all branches (--no-single-branch).

  • Specify the branch name using -b or --branch for --single-branch. The main (previously called master) branch is assumed, if not specified.

Warning Shallow clones cannot be pushed to a new repository. The shallow clone will either have to be [unshallowed] or the .git directory will have to be deleted (start afresh by initializing a new repository).
Related

git merge

Command

git merge <branch_name>

Prerequisites

The following terms are required to be understood:

Description

The git merge command’s primary responsibility is to combine separate branches and resolve any conflicting edits.

Merging is Git’s way of putting a forked history back together again.

The git merge command lets you take the independent lines of development created by git branch or git checkout and integrate them into a single branch.

Preparing to merge:

  • Make sure to be in the branch (git checkout <receiving_ranch>) you want to merge another branch into (let this branch be called receiving_branch).

  • Make sure the receiving branch and the merging branch are up-to-date with the latest remote changes.

  • Merge using git merge <merging_branch>

  • Eg: If you want to merge the 'feature' branch into the 'master' branch, run git checkout master (if you aren’t already in the master branch, ie, if your HEAD points to another branch) and then run git merge feature.

Note This does not create a new commit signifying the merge.
Note The branch can be safely deleted.

Merges are of mainly two types:

  • Fast forward merges (usually for small and short develop-duration features)

  • Three way merges (usually for long ranging tasks and features)

Types of merges
Note git push is allowed only if you have a fast forward merge.

Further details.

Note Managing merge conflicts (using both CLIs and GUIs).

Options/Flags

--abort

  • This will exit from the merge process and return the branch to the state before the merge began.

--no-ff <merging_branch_name>

  • If a fast forward merge is to be carried out, but even then create a new merge commit for the symbolic merging, this flag & option can be used.

  • The text editor will open for a message. Save the merge message and close the file in the editor to complete the merge.

Note This is useful for documenting all merges that occur in a repository, as a merge without this flag does not create a new commit.
Related

git branch

Command

git branch <flags> <options>

Prerequisites

The following term is required to be understood:

Description

The git branch command lets the user create, list, rename and delete branches.

It doesn’t let the user switch between branches or put a forked history back together again. For this reason, git branch is tightly integrated with the git checkout and git merge commands.

Further details.

Options/Flags

--list or <no_option>

  • List all of the local branches in the local repository.

-a

  • Lists all, ie, local and fetched remote branches.

<branch_name>

  • Creates a new branch, but this does not check out the new branch.

  • Use git switch or git checkout to check out (view/switch to) the new branch.

-d <branch_name>

  • Delete the specified branch.

Tip If the currently checked out branch is to be deleted, switch to a different branch and then run the above command.
Note This is a safe operation as Git prevents the deletion of the branch if it has unmerged changes.
-D <branch_name>

  • Force delete the specified branch, even if it has unmerged changes.

Tip If the currently checked out branch is to be deleted, switch to a different branch and then run the above command.
'-m <new_branch_name>' or '-M <new_branch_name>'

  • Rename the current branch to new_branch_name.

--show-current

  • Print the current name of the branch.

  • Does not print anything in the detached HEAD state.

Related

git checkout

Command

git checkout <flags> <options>

Prerequisites

The following terms are required to be understood:

Description

The git checkout command operates upon three distinct entities: files, commits, and branches.

The git checkout command lets you navigate between the branches created by git branch.

Further details.

Options/Flags

<new_branch_name>

  • Switches to / views / checks out a branch with the name new_branch_name.

  • Eg: git checkout feature_branch

Note git switch can also be used to achieve the same result.
-b <new_branch_name>

  • Creates a new branch & checks it out (switches to it) as well.

Note The new branch is created from the curent HEAD.
-b <new_branch_name> <existing_branch_name>

  • Creates a new branch & checks it out (switches to it) as well.

Note The new branch is created from the last commit of the existing_branch_name.
<commit’s_SHA>

  • You can checkout a specific commit.

Note This condition will land you in a detached HEAD state.
<file_name.ext>

  • To replace a modified file in the working directory/copy with the added/committed state version of that file.

  • If there are no staged changes, then the copy of the file in the local repository is used, otherwise the current file is overwritten by the staged copy of the file.

Note git restore can also be used to achieve the same result.
Related

git remote

Command

git remote <options_&_flags>

Prerequisites

The following term is required to be understood:

Description

Helps to make, view or break connections to other remote or local repositories.

To add a remote repo to a local repo:

  • Create a remote repo on GitHub, GitLab, BitBucket, etc.

  • On the CLI, type git remote add origin <link_to_repo>.git

Options/Flags

<no_option>

  • Lists the repos to which connections exist.

-v or --verbose

  • It gives the alias and corresponding URL of the connected repos.

add <connecting_repo_alias> <connecting_repo_url><.git>

  • To connect to a local or remote repo.

rm <connected_repo_alias>

  • Removes an existing repo connection.

  • Eg: git remote rm origin

Note This command only removes the connection between two repos. It does not delete any data.

git push

Command

git push -u <remote_repo_alias> <remote_branch_name>

Prerequisites

The following terms are required to be understood:

Description

This command is used to transfer files from the local repo to the remote repo.

To set up a remote repo, refer to git remote and [creating a repo on GitHub].

Warning If the push is to a newly created empty repository on GitHub, the main vs master default branch issue might cause it to fail.
Git push illustration
Fast forward merge
Note From the two pictures above, it can be inferred that Git will allow pushing only if the push results in a fast-forward merge.

git show

Command

git show <options>

Prerequisite

The following term is required to be understood:

Description

To see information about a specific commit or file. Use git log to get the SHA1 of the required commit.

Options/Flags

<commit’s SHA1>

  • To see more information about a specific commit than what git log <commit’s_SHA1> shows.

--name-only <commit’s SHA1>

  • To view just the name of the files changed in a particular commit.

:<file_name.ext>

  • To view the contents of committed or staged files.

  • Eg: git show :test_file.txt

Related

git stash

Command

git stash

Description

Saving changes temporarily.

Commands and explanation

git reset

git revert

git rebase

git bisect

git diff

git switch

Command

git switch <branch_name>

Prerequisites

The following term is required to be understood:

Description

Switch to/view/check out a branch.

Similar to git checkout.

Related

git restore

Command

git restore <file_name.ext>

Description

To replace a modified file in the working directory/copy with the added/committed state version of that file.

If there are no staged changes, then the copy of the file in the local repository is used, otherwise the current file is overwritten by the staged copy of the file.

Similar to git checkout.

Related

General #2

Merge Conflicts

CLI

GUI

Related

Sync a Fork with its Original Repo

  • Once a repository (repo) is [forked], the forked repo does not receive the latest commits in the original repo.

  • To get those new changes, the forked repo has to be synced with the original repo.

Note

  • GitHub has now made syncing a [forked repo] with its original repo very easy.

  • The GUI has buttons to directly do it (as shown in the image below, Fetch upstream → Fetch and merge). The changes in the synced forked repo only have to be pulled to reflect locally.

GitHub repo: Fetch upstream → Fetch and merge

  • The steps below will still work, but are unnecessary for repositories on GitHub.
Note The git pull step can be split into git fetch & git merge as well.

  • Summary of the important commands to sync a fork

$ git remote add originalRepo <link_to_original_repo>.git
$ git pull originalRepo <branch_name>
$ git push -u origin <branch_name>

(where originalRepo = original remote repo alias & origin = remote forked repo alias)

Related

Checkout a Remote Branch

There can be a situation in which a branch exists on the remote repo, but not in the local repo.

Branches on GitHub
Two branches in the remote repository
Local branches
Only one branch in the local repository

  • In such a situation, the remote branch needs to be fetched locally and then checked out to be used locally.

  • There are two possibilities

    • The remote branch has already been fetched locally, but not checked out.

    • The remote branch has not been fetched.

  • To check whether the remote branch has been fetched locally or not, run git branch -a. If the branch is listed in red, then it has been fetched locally.

If the Branch has been Fetched Locally

Local and fetched remote branches
'br_1' (in red) has already been fetched

  • Run git checkout <fetched_branch_name> or git switch <fetched_branch_name> to switch to the fetched remote branch.

Local and fetched remote branches
Successfully switched to 'br_1'!

If the Branch has not been Fetched Locally

Local and fetched remote branches
'br_1' has been not been fetched (not in list)

  • Fetch the branch using git fetch <remote_repo_alias> <branch_to_be_fetched>.

Fetched remote branch

  • Run git branch -a to check whether it appears as a fetched branch in red.

Local and fetched remote branches

  • Run git checkout <fetched_branch_name> or git switch <fetched_branch_name> to switch to the fetched remote branch.

Local and fetched remote branches
Successfully switched to 'br_1'!

Correcting Common Mistakes

There are some unwanted things everyone ends up doing while using Git and then one looks up the mistake to find a way to undo it.

The following points are solutions to some mistakes that everyone makes

Unstage Files Staged/Added by Mistake

A lot of times files are added/staged by mistake, no matter whether they are new or modified. The solution below will unstage all the files that were staged by mistake.

Prerequisites

Solution

Note The commands below will simply unstage added files and will NOT result in data loss.

  • General syntax: git reset HEAD -- "<files/folders/patterns>"

  • Files

    • For a single file, use git reset HEAD -- "<file_name.ext>".

    • For multiple files, use git reset HEAD -- "<file_1.ext>" "<file_2.ext>"…​.

    • For files with the same extension, use git reset HEAD -- "<*.ext>".

  • Directories/folders

    • For a single directory, use git reset HEAD -- "<path/to/dir>".

    • For multiple directories, use git reset HEAD -- "<path/to/dir_1>" "<path/to/dir_2>"…​.

  • To unstage everything in the staging area, use git reset HEAD or git reset HEAD -- *.

Git Internals

Moved to git.harshkapadia.me.

The .git Directory

Moved to git.harshkapadia.me.

Git Objects

Moved to git.harshkapadia.me.

Git Deep

Further resources for Git Internals.

Moved to git.harshkapadia.me.

GitHub

What is GitHub?

GitHub Repositories

  • What is a repository (repo)?

  • Who are collaborators?

  • Who are contributors?

  • There are two types of repositories on GitHub (These are remote repos)

    • Public repo

    • Private repo

  • Public repo

    • A public repository is a repo open for the world to view, download and use (ethically or unethically, depending upon the [license]).

    • Contributors can raise [issues] on the repo and make a [pull request (PR)] to it.

    • Collaborators and the owner can raise [issues] on the repo and push code to it.

    • It is a good way to improve the software and help others by showcasing the code and features as well!

    • A GitHub free user is allowed to make unlimited public repos with unlimited collaborators. (There is a limit on the number of collaborators that can be added by the owner/organisation in 24 hours.)

  • Private repo

    • A private repo is only open for viewing, downloading and uploading for the collaborator that the repo owner chooses.

    • A private repo will only have collaborators as contributors. Contributors can raise [issues] on the repo and make a [pull request (PR)] to it.

    • Collaborators and the owner can raise [issues] on the repo and push code to it.

    • This type of repo is usually used to work on a project with or without a team, privately.

    • A GitHub free user is allowed to make unlimited private repos with unlimited collaborators. (There is a limit on the number of collaborators that can be added by the owner/organisation in 24 hours.)

Related

Contributor Friendly Repository

Open source is all about opening up projects for the community to use and contribute to! Contributions are a very important aspect of open source. Contributions help the community in improving software/projects that they use, for themselves and others.

To make contributions easier, the following files/tools are used in a repository

They are discussed below.

Tip A good place to get to know how a repository compares with the recommended community standards and add the missing files is the 'Community' tab in the 'Insights' section of a repository.

README.md

  • The README.md file is where all the details of the project are written.

  • md stands for 'Markdown', which is a lightweight and very easy to learn markup language to create rich text using a plain text editor.

  • A README.md file usually includes a brief description of the project with its features, a link to the CONTRIBUTING.md file, a link to the CODE_OF_CONDUCT file, a link to the LICENSE file and any other section that the repository owner wants to add.

  • Sample template

# repo name (or logo/picture)
<Add badges (shields) here>
<Hosting URL of project (if any)>
<Tag line>

Description of project

## Features

Describe the features of your project.

## Technologies used

List all the technologies used

## Installation

Give steps to install and use your software/project. (Not for contribution purposes.)

## Contributions

Welcome all contributions & add a link to the `CONTRIBUTING.md` file.

## Code of Conduct

Add a link to the `CODE_OF_CONDUCT.md` file.
Note Source of the above template.

CONTRIBUTING.md

  • The CONTRIBUTING.md file explains how a contributor should do things like format code, test fixes, and submit patches. It can also include instructions for contributors to set up a local environment.

  • md stands for 'Markdown', which is a lightweight and very easy to learn markup language to create rich text using a plain text editor.

  • A sample template

License

  • An open source license protects contributors and users. Businesses and savvy developers won’t touch a project without this protection.

  • The need for an open source license.

  • The license under which a project is released can be changed at any time.

  • it’s hard to go wrong with the MIT license as it’s short, very easy to understand and allows anyone to do anything so long as they keep a copy of the license, including the repository owner’s copyright notice.

  • A good place to choose a license is https://choosealicense.com/.

  • A commonly used license can be added directly from the 'Community' tab in the 'Insights' section of a repository. If the license is not present in the license section, a file called LICENSE (without an extension) can be created and the content of the license can be pasted in it. (The contents can be found at https://choosealicense.com/.)

Warning

If certain software doesn’t have a license, that generally means that there is no permission from the creators of the software to use, modify or share the software. Although a code host such as GitHub may allow viewing and forking the code, this does not imply that anyone is permitted to use, modify, or share the software for any purpose.

The options are

  • Ask the maintainers nicely to add a license.

  • Don’t use the software.

  • Negotiate a private license with a lawyer.

Source of above warning

Code of Conduct

  • A Code of Conduct (CoC) facilitates healthy and constructive community behavior by establishing expectations for behavior for a project’s participants.

  • The Contributor Covenant is a common CoC used by open source projects.

  • A commonly used CoC can be added directly from the 'Community' tab in the 'Insights' section of a repository. If the CoC is not present in the CoC section, a file called CODE_OF_CONDUCT.md can be created and the content of the CoC can be pasted in it.

  • More information on CoC.

Issues

  • Most software projects have a bug tracker of some kind. GitHub’s tracker is called 'Issues', and has its own section in every repository.

  • Issues are a great way to keep track of tasks, enhancements, and bugs for projects. They’re kind of like e-mail, except they can be shared and discussed with the rest of the team.

  • If the repository is public, then anyone can raise an issue.

  • Labels

    • Issues have colour coded labels that help categorize and filter issues.

    • Every issue can have multiple labels that can be modified at any time.

    • Some labels are provided by GitHub and they can be custom created as well.

    • Labels for new/beginner contributors:

  • Issues and pull requests (PRs) can be referred to using #. Every issue and pull request has a number associated with it (usually mentioned at the top of the issue/PR, beside the title.) So #69 or #420 are examples of how issues/PRs can be referred to, in commit messages, PRs or issues.

  • Refer to GitHub’s guide for more on issues.

Terms

Repository

  • Git stores information in a data structure called a repository (repo).

  • Simply put, a repo is a place where the history of the user’s work is stored.

  • Types of repos

    • Local repo

    • Remote repo

      • Public repo

      • Private repo

    For more information on the types of repos, refer to the Repos & types section.

Related

Untracked Files

  • Newly created files are untracked files.

  • They are files that have never been added to the local repository.

  • In short: Untracked files are those files which are not in the .gitignore file and that have never been added to the repo.

Related

Added Files

  • All files not in .gitignore and that have been added to the staging area of the repository.

  • The files are in their latest version (ie, they have not been modified since they were last added).

  • They are also called 'staged files'.

Related

Modified Files

  • All files not in the .gitignore, that have been added to the repository (repo) and have been modified since.

  • The files are NOT in their latest version (ie, they have been modified since they were last added).

Related

.gitignore file

  • .gitignore is a file which tells git which files (or patterns) in the directory it should ignore.

  • It’s usually used to avoid committing transient files from the working directory/copy (a copy of the most recent state of the files you’re working on) that aren’t useful to other collaborators, such as compilation products, temporary files that IDEs create, etc.

Syntax

Ignore files locally without modifying .gitignore

  • You can ignore a file/folder only for your local repository without modifying .gitignore by adding a pattern in .git/info/exclude.

  • The syntax is the same as for .gitignore.

  • This is useful if you want to keep a local TODO list, but don’t want to commit it to the repository, and don’t want to modify .gitignore for everyone.

Related

Staging (staging area/index)

  • It notes the added files in the working directory/copy - a copy of the most recent state of the files you’re working on.

  • To stage a file is simply to prepare it finely for a commit.

  • Refer to the diagram.

  • Git, with its index allows you to commit only certain parts of the changes you’ve done since the last commit.

  • Further Details.

Related

Working Tree

  • It notes the untracked files in the working directory/copy - a copy of the most recent state of the files one is working on.

  • Any changes to files will be marked and seen in the Working Tree.

  • Here if one makes changes and do not explicitly save them to git, they will lose the changes made to their files.

  • If one makes changes to files in their working tree, git will recognize that are modified, but until they tell git “Hey pay attention to these files,” it won’t save anything that goes on in them.

  • Further details.

Related

SHA1

  • SHA = Secure Hashing Algorithm

  • It is a 40 digit hexadecimal number.

  • Every commit has a unique SHA1 associated with it.

  • All 40 characters are NOT needed for commands. The first 7 to 8 characters of the SHA1 will do.

Working of commit
Related

Aliases

[Aliases] make your Git experience simpler, easier, and more familiar…​
— Pro Git by Scott Chacon and Ben Straub
https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases

  • If you don’t want to type the entire text of each of the Git commands, you can easily set up an alias for each command using git config. Here are a couple of examples you may want to set up:

    git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status

    This means that, for example, instead of typing git commit, you just need to type git ci. As you go on using Git, you’ll probably use other commands frequently as well; don’t hesitate to create new aliases.

  • An alias can be given to the remote repo as well, to make pulling and pushing easier.

    • You can set custom aliases if you add a remote (ie, remote repo) using git remote.

    • If you clone a repo using git clone, the default alias of the remote repo is origin.

Related

HEAD

  • HEAD is a reference to the latest commit in the current branch.

  • When a commit is made, Git automatically sets the HEAD to the latest commit.

Note HEAD is contextual. It will point to the latest commit in the current branch.
Working of Commit

  • To check where the current HEAD is pointing, run cat .git/HEAD in the root directory.

    • Eg:

      # in the 'main' branch
$ cat .git/HEAD
ref: refs/heads/main
$ git switch test_branch
Switched to branch 'test_branch'
$ cat .git/HEAD
ref: refs/heads/test_branch

  • When the HEAD points to a commit that is not the latest commit in a branch, that is a detached HEAD. A specific commit can be referred to, using git checkout.

Related

Branches

Branches

  • In Git, branches are a part of everyday development process.

  • Git branches are effectively a pointer to a snapshot of changes.

  • When a new feature is to be added or a bug — no matter how big or how small has to be fixed, a new branch is created to encapsulate the changes.

  • This makes it harder for unstable code to get merged into the main code base, and it gives the chance to clean up the future history before merging it into the main branch.

Default Branch

  • The default branch is considered as the base branch.

  • It is usually the most up to date/stable code version.

  • Importance

    • This is the branch that is cloned on running git clone.

    • All pull requests are opened against this base branch unless any other branch is explicitly specified.

  • Any branch can be made the default branch, but by default it is the 'master' (or 'main') branch.

  • The default branch can be changed at any time on GitHub from the repository’s settings and GitHub will point all open pull requests to the new default branch.

  • Changing the default branch of the local Git client (using git config) is also possible. If this is done, whenever a new repository is initialized locally, the default branch will be the new branch name entered in the git config command.

Related

Collaborators

  • Collaborators are the repository (repo) owner’s team members/partners.

  • A collaborator has a lot of accesses that a repo owner has.

  • They can directly push to the repository, merge PRs, etc.

  • The owner of the repo can invite any number of collaborator from the settings/manage access section in the repo (there is a limit to the number of invites in 24 hrs).

Note A contributor is a collaborator only if he is chosen to be a collaborator by the owner. So a collaborator is a contributor, but the vice versa is not always true.
Related

Contributors

  • Contributors are people who contribute to repositories to make them better.

Note A contributor is a collaborator only if he is chosen to be a collaborator by the owner. So a collaborator is a contributor, but the vice versa is not always true.

General contributor instructions

  • [Fork] the repo.

  • clone the forked repo locally.

  • Work on the contribution(s) according to the [issues] and/or [CONTRIBUTING.md].

Tip Follow correct commit message structure. Eg: :bug: fix: Login button position corrected (#26, #32, #33)

  • Push the code to the forked repo.

  • Make a [pull request (PR)]!

Related

Misc

Open Source Programs

Table of Contents

Google Summer of Code

GSoC Logo

Google Summer of Code (GSoC) is a global open source program where students can contribute to projects of organisations participating in Google Summer of Code for 10 weeks to gain exposure in the Software Development field and the participant will be paired with a mentor and get to learn various things in the domain of their interest. GSoC also provides a stipend to the participants.

To participate in GSoC, it is recommended to contribute to an organisation of interest 2 to 3 months before the GSoC applications start.

GSoC

GSoC Organisations

Google Season of Docs

GSoD Logo

Google Season of Docs (GSoD) provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source.

GSoD

Beginners Guide to GSoD

Outreachy

Outreachy Logo

Outreachy is a three month long paid and remote internship for people who are underrepresented in specific fields. It is conducted twice a year.

Important

  • Students who have participated in Google Summer of Code are not eligible for Outreachy.

  • Students whose university lies in the Northern Hemisphere are eligible to apply only for the first application round and those whose university lies in the Southern Hemisphere are eligible only for the second round. Those whose university lies near the Equator are eligible to apply in both the application rounds.

The application process of Outreachy

  • Initial Application Period

    • For the initial application one needs to write five essays on the questions asked in the application. These essays are basically to understand whether one belongs to an underrepresented group or not.

    • One is selected for the next step on the basis of these essays.

  • Contribution Period

    • Now the list of projects will be released and participants need to contribute to their chosen projects and contact mentors.

    • They also have to fill the final application.

  • Intern Selection Period

    • Mentor will tell Outreachy organizers which intern they want and a final announcement for selected interns will be made.

Outreachy

Beginners Guide to Outreachy

Major League Hacking Fellowship

MLH-logo

Major League Hacking (MLH) Fellowship is a 12 week internship program designed to level up Tech Skills. The Program is divided into three tracks

  • Open Source

    • This track is about contributing to some great open source projects that are used by thousands of companies around the world.

  • Software Engineering

    • This track is about working on real-world Software Engineering problems by collaborating on projects by real companies and Government partners.

  • Prep Program

    • THis track is about building out one’s portfolio and experimenting with new technologies by collaborating in a short hackathon sprint.

MLH Fellowship

Beginners Guide to MLH Fellowship

Linux Foundation Mentorship Program

Linux-foundation-logo

The Linux Foundation Mentorship Program gives one an opportunity to learn from open source contributors and contribute to open source projects.

Current mentorship programs include

  • Linux Kernel

  • LF Networking

  • Hyperledger

  • CNCF

  • OpenHPC

  • Open Mainframe Project

  • GraphQL

Linux Foundation

Beginners Guide to the Linux Foundation Mentorship Program

Summary

Name Timeline Links Eligibility

Google Summer of Code (GSoC)

Oct-Aug

GSoC

GSoC Organisations

For Students:

Age should be at least 18 years.

Should be enrolled in a Post-Academic Program.

Student must be eligible to work in the residing country for the duration of the program.

Should should not be an Organisation Administrator or Mentor in the program.

Google Season Of Docs (GSoD)

Feb-Nov

GSoD

Beginners Guide to GSoD

Outreachy

May-Aug

Dec-March

Outreachy

Beginners Guide to Outreachy

Students who have participated in GSoC are not eligible for Outreachy.

Students whose university lies in the Northern Hemisphere are eligible to apply only for the first application round and those whose university lies in the Southern Hemisphere are eligible only for the second round. Those whose university lies near the Equator are eligible to apply in both the application rounds.

MLH Fellowship

Spring batch: Jan-April

Summer batch: May-Aug

Fall batch: Sept-Dec

MLH Fellowship

Beginners guide to MLH Fellowship

Age should be above 18 yrs.

Student should be able to spend the hours required by the program.

Linux Foundation Mentorship Program

Spring term: March-May

Summer term: June-Aug

Fall term: Sept-Nov

Linux Foundation

Beginners Guide to the Linux Foundation Mentorship Program

Resources

Sessions by the Author

Getting Started with Git and GitHub

Contribution Help

GitHub Issues

Visualization

Documentation

Browser Extensions for GitHub

  • Refined GitHub

    • Simplifies the GitHub interface and adds useful features.

  • GitZip for GitHub

    • Only download required directories/files from GitHub repos.

  • Octotree

    • Add a navigation pane to the left of a GitHub repo to navigate it easily.

Articles

Advanced

Kindness always wins.
— Selena Gomez
We rise by lifting others.
— Robert Ingersoll
Alone we can do so little; Together we can do so much.
— Helen Keller