NOTE, 1 October 2020 the label ‘master’ was replaced by ‘main’ for the default repo branch.
Introduction
This post covers connecting a local git clone to a remote master at gitHub.com. The post is inspired by the Youtube Introduction to Git - Remotes by David Mahler, and the written post ‘Git’ with the Program: Getting Started with GitHub.
Prerequisites
Apart from having git installed you must also have a secure shell (SSH) connection if you want to follow this tutorial in detail. You can also use HTTPS for connecting to GitHub.com, then you do not need an SSH setup, but you need need to give your GitHub credentials when you want to connect for your local machine to your online GitHub account. If you do not have an online GitHub account, the next step is to get one.
Create GitHub account + repo
GitHub is free for private users that are satisfied with public repositories. You just sign up, give your email and once you have confirmed your register via your email, and given answers to some simple questions about experiences and interests, you will land at the page “Create a new repository”.
If you do not get to the page “Create a new repository”, use the navigation menu next to the avatar to select “New Repository” (as shown to the right).
Go ahead and create you first repo, the figure below shows the fields to fill.
You have to give the repo a name. Also fill in a Description and let the repository be Public (to use Private repos comes with a fee). Click the check boxes for Add a README file, Add .gitignore and Choose a license as appropriate. Click and behind the scenes GitHub is staging and commiting.
When ready, GitHub will open a page with your repo. If there is a pop-up window inquiring about GitHub Actions (as shown to the right), just click .
Your first GitHub repo is created, including one (1) commit at branch master that locked in the README.md markdown document. All summarised on the repo page shown below.
Grab the SSH for a repo
Towards the right side, approximately mid down there is a button (shown below - in older version it was labelled [Clone or Download]). Click on it.
In the pop-out window select “SSH” and the setting will change to Clone with SSH. And then copy the string in the textbox starting with git@github.com…. This string will allow us to connect from a local git repo directly to the remote repo on GitHub.
Clone to local repo
Open a Terminal window and cd to the parent directory where you want to create the clone of your remote (GitHub) repository. Then type (but do not execute):
$ git clone
If you followed the instructions in the previous section, you can now just paste the SSH link from your clipboard to the command line:
$ git clone git@github.com:thomasgumbricht/my-first-repo.git
Execute the command and your remote repo (“my-first-repo”) should clone to your local machine. If this is the first time you use the SSH key, you will be prompted the following statement and question:
Cloning into 'my-first-repo'...
The authenticity of host 'github.com (140.82.118.4)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no)?
Answer with a full yes
Warning: Permanently added 'github.com,140.82.118.4' (RSA) to the list of known hosts.
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
Receiving objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Local repo settings
The post on Local git control explains how to Check and setup user name. For the cloned repo (“my-first-repo”) you can setup a local user and email that matches the SSH key. As I created this repo as a trial, I need to set my user and email. First cd to the clone of the repo, and then set user and email:
$ cd my-first-repo
$ git config user.name thomasgumbricht
$ git config user.email thomas.karttur@gmail.com
Verify your configuration by displaying your configuration file:
$ cat .git/config
git remotes
The command git remote returns the remotes for the repo. With the terminal window still pointing to the cloned repo (“my-first-repo”), type:
git remote
origin
The name origin is like a git alias for the default remote repository. To see the full paths (urls) and the rights that we have for remotes, type:
git remote -v
origin git@github.com:thomasgumbricht/my-first-repo.git (fetch)
origin git@github.com:thomasgumbricht/my-first-repo.git (push)
git log
In some of the earlier posts the following command was introduced as a means to get a condensed graphical view of the branches and the commit history:
$ git log --all --decorate --oneline --graph
* 9f30e5b (HEAD -> master, origin/master, origin/HEAD) Initial commit
For the clone we are working with the HEAD pointer points towards two new items: origin/master and origin/HEAD. As origin can be seen as an alias for the primary remote repo, the pointing is towards the remote (GitHub) repo. As HEAD is pointing both towards the local master and the remote master, our local repo is in sync with the GitHub repo.
Edit origin/master
To try the different functions for linking a remote and a local repository, return to your online GitHub account and the origin/master repo (“my-first-repo”). When in that repo, click the button.
In the window that opens, give the name of the new document in the textbox that says Name your file…. Then enter a few lines in the area for Edit new file..
When done, scroll down towards the bottom of the page, GitHub has created a default (short) message. If you accept that message just click the button.
The edits you made are staged and commited by GitHub, and you are returned to the front page of your online repo. It now says you have two commits, and in the list of contents you can see two files, each with its own commit.
git fetch
Return to the Terminal window that points to your local clone. Your local copy should now be behind the online (orign/master). However, your local git is not yet aware of the latest online commit. You can check that out by either git status or git log. For your local git clone to catch up with online changes, you need to run git fetch.
$ git fetch
or
$ git fetch origin
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
From github.com:thomasgumbricht/my-first-repo
9f30e5b..9cd2c08 master -> origin/master
Check the status of your local repo:
$ git status
On branch master
Your branch is behind 'origin/master' by 1 commit, and can be fast-forwarded.
(use "git pull" to update your local branch)
nothing to commit, working tree clean
You can explore the situation graphically:
$ git log --all --decorate --oneline --graph
* 9cd2c08 (origin/master, origin/HEAD) Create Chapters.md
* 9f30e5b (HEAD -> master) Initial commit
The local master is trailing origin/master.
git merge
The post on git branches outlines how to use git merge. As you have not done any edits to your local (receiving) repo, the merge of the origin/master can be done as a fast-forward merge (straight update of the HEAD pointer to the latest commit):
$ git merge origin/master
Updating 9f30e5b..9cd2c08
Fast-forward
Chapters.md | 5 +++++
1 file changed, 5 insertions(+)
create mode 100644 Chapters.md
You can check that your local clone is in sync with orgin/master by either git status or git log.
git pull
The git pull command combines git fetch and git merge into a single command. Both online GithHub repos and the Github Desktop app have predefined functions for pull (rather than fetch + merge). It is, nevertheless, often better to use fetch + merge.
git push
The command git push is used for sending local clone changes to remote repos. To test it, make some edits to the local copy of Chapters.md. You can use any editor, for instance pico:
$ pico Chapters.md
...
## Add another chapter
Hit [ctrl]+[X] to exit pico and save the edits by pressing Y when asked.
commit the changes with the combined command:
$ git commit -am "Added chapter to Chapters.md"
[master 0b4547f] Added chapter to Chapters.md
1 file changed, 2 insertions(+)
The local clone of the repo is now 1 commit ahead of origin/master. To put them in sync again, git push the local changes to the remote repo:
$ git push origin master
or afer 20201001
$ git push origin main
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 339 bytes | 169.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:thomasgumbricht/my-first-repo.git
9cd2c08..0b4547f master -> master
A quick look at your GitHub online repo (remember to refresh the page) reveals that you have now three commits, with the latest message being “Added chapter to Chapters.md”.
Resources
Pro Git - Everything you need to know about git by Scott Chacon and Ben Straub (20200219).
Learn Git with Bitbucket Cloud
Youtube tutorial Introduction to Git - Remotes by D. Mahler (20170621)