Getting Started with GitHub – Step by Step Walk-through

Note: This post is part 1 of three-part Getting Started with Git & GitHub post series. This learning post is still in active development and updated regularly.

In the previous Learning to Work With Git and GitHub learning series,  Git essentials with common terminology and commands were assembled. In this Getting Started with Git & GitHub three parts series, step-by-step procedure to getting started using Git & GitHub including creating local repository, branching and Git project management will be discussed.

The objective this part 1 of the three part series is to learn how to work with Git by creating GitHub account,  SSH key authentication to local Mac to connect to github.com account for GitHub project management (pull, push, commit, merge, etc), and creating local depository will be discussed.

Creating a GitHub Account

Step 1: Create an account at GitHub.com

Its very basic. Select any username, enter email address and a password and click Sign up for GitHub button. After e-mail verification, it prompts to an following window.

Step 2: Create a New Repository

In GitHub speak, a repository is “project’s folder, a basic element of GitHub”. To create a new repository click + sign drop down menu at the top right corner of the page (see below).

Enter name of your repository (eg. demo, my-github-project, etc) and click Create Repository button. Now the account page displays with a project repository.

The next step is to create a project repository in our local machine (eg. Mac laptop). However before that step, we will first authenticate our local Mac with the GitHub account.

Authenticating with GitHub

Its important to setup your local machine with SSH authentication. This allows all operations to/from GitHub (clone, pull, push and others) could be performed without authentication (user and password) every time.

The following instructions are sourced from GitHub documentation.

Step 1: Check for any existing SSH Keys. Type the following in Terminal window:

#! check for any SSH key
$ ls -al ~/.ssh

#!output
ls: /Users/username/.ssh: No such file or directory

The No such file or directory output return means there is no SSH key configured yet. If there were existing public SSH keys, it outputs default files named either id_rsa.pub or id_dsa.pub. Since there were no SSH keys, we will generate a new key in step 2.

Step 2: Create a SSH Key. To generate a new key, type the following in the terminal window:

#! create a new SSH key
ssh-keygen -t rsa -b 4096 -C youraddress@gmail.com # add your email address

Change the email address field with actual e-mail address. This creates a new ssh key, using the provided email as a label.

#! select prompt
> Enter a file in which to save the key 
(/Users/you/.ssh/id_rsa): [Press enter]

When prompted “enter a file in which to save the key,” select Enter to continue.

Step 3: Secure passphrase. When prompted for secure passphrase, it can be skipped safely.

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

Verify the newly generated SSH key as shown below:

#! at terminal type
$ ls -al ~/.ssh
#! output
drwx------   4 username  staff   128 Jan 15 15:34 .
drwxr-xr-x+ 37 username  staff  1184 Jan 15 15:31 ..
-rw-------   1 username  staff  3389 Jan 15 15:34 id_rsa
-rw-r--r--   1 username  staff   747 Jan 15 15:34 id_rsa.pub

Step 4: Add your SSH key to the ssh-agent. For mac machine, type the following in the terminal:

Start the ssh-agent in the background.

#! at terminal type
eval "$(ssh-agent -s)"
#! Output
Agent pid 6847

Add your SSH private key to the ssh-agent

#!
$ ssh-add ~/.ssh/id_rsa
#! output
Identity added: /Users/username/.ssh/id_rsa (name@gmail.com)

The username & name (in email field) will be your actual username & e-mail address.

Step 5: Copy your SSH key to the clipboard with the following (in Mac):

#! at Mac terminal
pbcopy < ~/.ssh/id_rsa.pub
#! output
No output but its copied on the clipboard

No output is returned but the SSH key is copied in the clipboard.

Step 6: ADD new SSH Key to GitHub account profile.

• Your GitHub Account Settings
• In the user settings left sidebar, click SSH and GPG keys.
• Select New SSH key or Add SSH key on the right.
• Give an identifying title of your machine (eg. “My Mac Desktop”) and paste the public key into the text box.
• Click Add SSH key.
• If prompted, confirm your GitHub password.

Step 7: Finally, authenticate your local machine

#! at Mac terminal
ssh -T git@github.com
#! Output
 Hi username! You've successfully authenticated, but GitHub 
 does not provide shell access.

The above output “You’ve successively authenticated” confirms that the local machine SSH key has been authenticated with the GitHub account.

Working with Local Git Projects

Because bulk of the work will be done in local machine, lets clone the remote (from GitHub) repository to local Mac.

To test whether GitHub account & local SSH key authentication with the remote (GitHub) was set up correctly, we will do a small for testing & verification purposes.

Create a Local Project Repository

Step 1: Know and confirm your location

#! check directory
pwd
#!output
/user/yourname

Step 2: Create a project folder named my-hello-world.

#! make directory
mkdir demo-project

#! list directories
ls
#! Output
demo-project

The mkdir command instructs to make a directory name my-hello-world. Give this name same as the GitHub.com repository name. The ls command in line 5, lists all the files in the directory. In our case there is one only file my-hello-world.

Step 3: Move into the new project directory.

#! change to project directory
cd demo-project

The cd (change directory) command directs to the my-hello-word directory. This is where our project files are going to live.

Step 4: Initialize Git repository from the project folder.

#! initialize git
git init
#!Output
/Users/username/demo-project/.git/

The Git init command stand for initialization and all Git commands begin with git. This command “turns an existing directory into a git repository”. This creates .git/ directory (hidden) in the project directory.

Step 5: Configure your global git account

#! config global 
git config --global user.name "your_name"
git config --global user.email your_email@email.com

Note: This step can be skipped if Git user.name and user.password has been configure globally.

Step 6: Create a README.md file in the repository

An empty file can be created beginning with touch followed by filename (eg. README.md). The “touch” command means “create” which creates an empty file.

#!create empty README.md file
touch README.md

#! edit using atom editor
$ atom README.md
#! add the following in the README.md
# DEMO PROJECT
This is a demo project README Doc.

After editing README.md file save the file.

Alternately, small file edits can be done with echo command as well followed by text inside the double quote ("..") and file name as shown below.

#!create READ.md file
echo "# Demo Project" >> README.md

The code creates a README.md file with “Demo Project” as its header.

Step 7: List the repository with ls command

#! list the file in depository
$ ls
#! output
README.md

The output list one README/md file in the repository. However the file is tracked by Git yet because it has not been added to repository.

Step 8: Check status of repository

Because the README.md file has not been added to the local git repository, it fails to track.

#! check file status before adding
git status
#! output
On branch master
Untracked files:
(use "git add ..." to include in what will be committed)

 Readme.txt

As shown in the line 5, the newly created file is not tracked. It needs to be added to the git directory first (step 9).

Step 9: Add the README.md file and also commit it to the repository

#! add file to git repository
git add README.md
#! commit the README.md file
git commit -m "adding README.MD to repo"
#! output
[master (root-commit) 5e08629] adding README.MD to repo
 1 file changed, 2 insertions(+)
 create mode 100644 README.md

The file is added to the repository with add command (line 2). Then the README.md file is committed with commit -m command where -m means message in the double quotes “adding README.md to repo“. The commit output (lines: 6-8) shows file has been created and added to the repository. Now the file can be tracked because it has been added & committed to the repository.

Step 10: Login to remote (GitHub.com) Create an empty repository with the same name “demo-project“.

Step 11: Now PUSH (upload) the changes to the remote GitHub.com repository.

#! push project to remote
git push -u origin master
#! output
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 4 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 276 bytes | 276.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/username*/demo-project
 * [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'

The above output displays that the README.md file was successfully pushed from the local machine to the remote master branch. Now let’s check the remote server.

Step 12: Check the remote GitHub.com account repository by signing in to your account.

The above screenshot displays that the README.md file from local repository was pushed to the remote GitHub.com account and showing single README.md file.

Useful Troubleshooting help links: Using SSH over the HTTPS port & Testing your SSH connection

Wrapping Up

In this Git learning learning post, how to create a GitHub account,  authenticating local machine SSH key to github.com account for project management (pull, push, commit, merge, etc), and testing the setup with a simple local repository were discussed.

Next: Learning to Add, Modify, Delete and Branch Git commands in a GitHub repository

Useful Reference

While preparing this post, I have referred the following references extensively. Please refer to original posts for more detailed information.

• How to authenticate with GitHub using SSH | Cheatsheets.xyz
• Kent Dodds Egghead.io video
• Your first time with git and github | kbroman.org
• Using SSH over the HTTPS port | GitHub Help
• Testing your SSH connection | GitHub Help
• The Ultimate Git Beginner Reference Guide | mukulrathi.com