How to Sync and Update a Forked Repository
September 18, 2020
In this article, we shall briefly look at how we can submit work and contributions to a GitHub team project. This article assumes that you have a GitHub account. Check these instructions on how to create a GitHub user account. Before we get started, you need to understand the following terms, as you will constantly come across them in daily GitHub workflow.
Getting started
- Fork is a copy of a repository of someone’s else project. Forks allows you have to have a repository of a project that you do not own on your GitHub account so that you can make some changes without affecting the original repository. Once the changes on your forked repository are validated, you can submit these changes as contributions to the original project. Forks allows you to make your contributions to a team project.
- Remote a repository on GitHub account exists as a remote repository.
- Clone is downloading a copy of the remote repository to local computer.
- Commits are changes made to a repository. Committing saves edits/changes to our GitHub repository. With GitHub, every commit you make has a specific signature/ID the keeps the record of the changes you have made. If you happen to make a wrong change, you can revert the commit and your remote repository will be as it was before you made the changes. A commit has a commit message that allows you to have a brief description of the changes you are making.
- Push is used to transfer commits made on a local repository to a GitHub remote repository. To push to GitHub you make a push request to update your local commits to your remote repository.
- Branch a feature branch or base branch. A feature branch typically helps you to isolate your changes from the other team as you make and test these changes. The base branch consists of merged feature branches.
- Pull request is to notify the project team of the changes you have made from a pushed branch in your GitHub repository or basically requesting the owner of the repository to pull changes you made, thus called a pull request. A collaborator can be assigned to review your pull and propose any potential changes you need to make. Review changes are done with commits. Once changes and reviews are complete a team contributor or you (with access), can merge your branch to the base branch of the original repository.
- Merge is merging two branches and integrating them into a single branch. A merge conflict can happen if the two branches you are attempting to merge have both modified the same part of the same file. In such a case, Git will not be able to automatically choose which version to use.
How to fork
Now that you know, what a fork is, let’s see how you can fork a repository to start working on your changes and contribute to a team project. Forking a project on GitHub is really easy, you just need to hit the fork button. On your GitHub account, go to the repository you want to fork. In this example, we are referring to https://github.com/section-io/engineering-education. To the upper left corner, click on the fork button and you will have successfully forked the repository.
Now you have a copy of the original repository on your GitHub account.
To start pushing, committing, and pulling, you need clone the repository you have forked (on your GitHub account) and a have copy on your computer to start working on your contributions.
How to clone
Cloning using GitHub desktop
If you are using the GitHub desktop app, cloning a repository is as easy as pie. To get started, download GitHub desktop and install it into your computer and authenticate and configure it with your GitHub account.
To make GitHub desktop work easier, make sure you configure GitHub desktop with a text editor such as Visual Studio Code.
Once that is done, your GitHub account will load on the GitHub desktop. To start cloning, navigate to File then clone repository.
A clone window will pop up, you will be able to see the repositories in your account, and choose the repository you want to clone.
Alternatively, you may use the URL from GitHub remote repository, paste on the clone box of GitHub desktop, and initiate cloning, select your preferred location of the cloned repository to your local computer and you are done.
Cloning using Git Bash
Git uses protocols to transfer data from a remote server to your local machine. The main used URL protocols include:
- SSH (Secure Shell) is an authenticated network protocol that needs credentials (a password) before making a connection to the hosting server. This is how a SSH link looks like:
git://host.xz[:port]/path/to/repository.git
Example
git@github.com:section-io/engineering-education.git
- HTTP/HTTPS (Hyper text transfer protocol). The protocol of the web, most commonly used for transferring web page HTML data over the Internet. Git can be configured to communicate over HTTPS with encoded data transmission.
http[s]://host.xz[:port]/path/to/repository.git/
In this article, we shall use SSH URL protocol using Git Bash to execute git commands. However, to get started with Git Bash, you need to do the following authentication.
First, download and install git, launch Git Bash and sign in to your GitHub account using the following commands.
NOTE: remember to press enter after any of the following
git config --global user.name "your github account username"
git config --global user.email "your github account email"
Run
git config --global user.name
to confirm username and
git config --global user.email
to confirm email. To connect to your GitHub account you need to generate an SSH key. Run
ssh-keygen -t rsa -C "your github email"
Use the same email as your GitHub account email. After pressing enter on this command, you will be required to enter a password twice (this is not your GitHub password), enter any password of your choice, and when asked for confirmation renter the password again. An SSH code will be generated and you need it to authenticate the protocol. To open the file created, run
notepad ~/.ssh/id_rsa.pub
The file contains the SSH code, copy the key, and follow these instructions.
- On your GitHub account, go to settings
- Go to SSH and GPG keys
- Then new SSH key
- Enter the title “your key”
- Paste the copied SSH key in the big box
- Run command
ssh -T git@github.comto check if the configuration is ok
This should give you the following message Hi username! You’ve successfully authenticated, but GitHub does not provide shell access. Now you are good to go with SSH protocol
To start our clone run git clone (SSH URL)
Example
git clone git@github.com:kimkimani/engineering-education.git
Output
Cloning into 'engineering-education'...
Enter passphrase for key '/c/Users/kim/.ssh/id_rsa':
remote: Enumerating objects: 20, done.
remote: Counting objects: 100% (20/20), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 9676 (delta 8), reused 14 (delta 4), pack-reused 9656
Receiving objects: 100% (9676/9676), 108.32 MiB | 116.00 KiB/s, done.
Resolving deltas: 100% (5361/5361), done.
Updating files: 100% (785/785), done.
NOTE: make sure the link you copy is SSH. And remember to use the password you used when generating the SSH key to make authentication for passphrase for key '/c/Users/you/.ssh/id_rsa\': If you do not enter the SSH password, you will run into the following output Please make sure you have the correct access rights and the repository exists.
A copy of the remote is now available on your local computer on the location you entered on the Git Bash command with the folder name the same as the name of the repository in the remote repository. In case you want to have a different project folder use the clone command followed by the name of your preferred folder.
git clone git@github.com:section-io/engineering-education.git folder-name
When using a forked repo, the original repository will regularly be updated with commits. These commits are not directly updated to your repository, thus you need to regularly update your fork to keep it up to date with the original repository.
Updating a fork using GitHub web UI
The process is simple and clear. Go to your forked repository in your GitHub account, you will see the number of commits that the original repository has, and have and not been updated to your forked repository.
Click compare.
Use switch to base link.
If the switch to base is not available, use the dropdown to manually select the repositories to compare. When the comparing selections are correctly selected, you will be able to see the commits that are not updated to your fork.
Continue to the green button and create a pull request.
Enter a title “updating my fork”, comment as well, and proceed to create a pull request.
Scroll to merge request.
Confirm merge.
And you are done, your fork is now updated successfully. The fork is updated on the remote and you now need to update the changes to your local repository. Go to your GitHub desktop and make sure your current repository you are working with is selected.
You will able to see a “pull origin”. What this does is it pulls the remote changes to your local repository.
Click “pull origin” and your local repository will be updated and the same as the remote repository.
Summary
Updating a fork using Git Bash.
You have successfully forked your interested repository. However, you occasionally need to keep it up to date with the original repository. The original repository is commonly referred to upstream by Git Bash command.
To update your fork with the upstream, you need to get the remote to your local repository so that you can fetch available changes made in the original repository and push the changes to your local repository.
To get started navigate to your cloned repository (already on your local computer) and open the project folder with Git Bash or open Git Bash and change the directory to point the cloned repository on your local storage. i.e.
cd ~/Documents/GitHub/engineering-education
By default, your local repository is not directly linked to the original repository. Configure the remote upstream to be available locally.
git remote -v
OUTPUT
origin git@github.com:kimkimani/engineering-education.git (fetch)
origin git@github.com:kimkimani/engineering-education.git (push)
At this point, only the original repository is linked (The remote repository that you forked from the original). Link your repository with the remote or the original repository.
git remote add upstream <ssh url from the original repository>
git remote add upstream git@github.com:section-io/engineering-education.git
Run
git remote -v
To confirm if your remote upstream is available on your local repository origin.
Output
git@github.com:kimkimani/engineering-education.git (fetch)
origin git@github.com:kimkimani/engineering-education.git (push)
upstream git@github.com:section-io/engineering-education.git (fetch)
upstream git@github.com:section-io/engineering-education.git (push)
What you need now is to fetch the changes/commits from the upstream
git fetch upstream
Output
Enter passphrase for key '/c/Users/kim/.ssh/id_rsa':
remote: Enumerating objects: 139, done.
remote: Counting objects: 100% (139/139), done.
remote: Compressing objects: 100% (66/66), done.
remote: Total 131 (delta 88), reused 105 (delta 65), pack-reused 0
Receiving objects: 100% (131/131), 696.24 KiB | 11.00 KiB/s, done.
Resolving deltas: 100% (88/88), completed with 8 local objects.
* [new branch] EngEd-template-idea-form -> upstream/EngEd-template-idea-form
* [new branch] add-section-home -> upstream/add-section-home
* [new branch] address-resolution-protocol -> upstream/address-resolution-protocol
* [new branch] authors-link -> upstream/authors-link
* [new branch] clustering-algorithms -> upstream/clustering-algorithms
* [new branch] documentation -> upstream/documentation
* [new branch] fix-topic-capitalization -> upstream/fix-topic-capitalization
* [new branch] fixing-blank-author-pages -> upstream/fixing-blank-author-pages
* [new branch] fourth -> upstream/fourth
* [new branch] introduction-web-assembly -> upstream/introduction-web-assembly
* [new branch] knapsack -> upstream/knapsack
* [new branch] make-author-pages-work -> upstream/make-author-pages-work
* [new branch] man-in-the-middle-attack -> upstream/man-in-the-middle-attack
* [new branch] master -> upstream/master
* [new branch] matplotlib-visualization-python -> upstream/matplotlib-visualization-python
* [new branch] nodejs-backend-frontend -> upstream/nodejs-backend-frontend
* [new branch] nodejs-cta-blocks -> upstream/nodejs-cta-blocks
* [new branch] pr/54 -> upstream/pr/54
* [new branch] private-block-chain -> upstream/private-block-chain
* [new branch] quality-checker-action -> upstream/quality-checker-action
* [new branch] remove-articles -> upstream/remove-articles
* [new branch] remove-unused-topic-pages -> upstream/remove-unused-topic-pages
* [new branch] site-mapping -> upstream/site-mapping
* [new branch] supervised-machine-learning -> upstream/supervised-machine-learning
* [new branch] testing-author-page-blank -> upstream/testing-author-page-blank
* [new branch] vlan-trunking -> upstream/vlan-trunking
* [new branch] vm-vs-containers -> upstream/vm-vs-containers
You have fetched the changes, commits, and branches that you need to merge to the head branch. Before doing the merge, make sure you are updating this changes on your master.
git checkout upstream/master
Output
Note: switching to 'upstream/master'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command.
Example:
git switch -c <new-branch-name>
Or undo this operation with:
git switch -
Turn off this advice by setting config variable advice.detachedHead to false
HEAD is now at 1335657 Merge pull request #272 from kimkimani/most-useful-NodeJs-packages
git checkout master
OUTPUT
bash Previous HEAD position was 1335657 Merge pull request #272 from kimkimani/most-useful-NodeJs-packages Switched to branch 'master' Your branch is up to date with 'origin/master
This points to the branch you are already on, once on the master branch, merge it with the upstream.
git merge upstream/
Output
Updating d9acac5..646cb27
Fast-forward
articles/huffman-coding-in-python/hero.jpg | Bin 0 -> 27160 bytes
articles/huffman-coding-in-python/Code_Output.jpg | Bin 0 -> 16932 bytes
articles/huffman-coding-in-python/index.md | 185 ++++++++++++++
articles/huffman-coding-in-python/optimaltree.jpg | Bin 0 -> 48468 bytes
.../stripe-integration-react/api_test_keys.jpg | Bin 0 -> 160402 bytes
articles/stripe-integration-react/dashboard.jpg | Bin 0 -> 147132 bytes
articles/stripe-integration-react/final_output.jpg | Bin 0 -> 90318 bytes
articles/stripe-integration-react/hero.jpg | Bin 0 -> 30446 bytes
articles/stripe-integration-react/index.md | 281 +++++++++++++++++++++
articles/stripe-integration-react/paymentflow.jpg | Bin 0 -> 71723 bytes
articles/stripe-integration-react/paywithcard.jpg | Bin 0 -> 65169 bytes
11 files changed, 466 insertions(+)
create mode 100644 articles/huffman-coding-in-python/Code_Output.jpg
create mode 100644 articles/huffman-coding-in-python/hero.jpg
create mode 100644 articles/huffman-coding-in-python/index.md
create mode 100644 articles/huffman-coding-in-python/optimaltree.jpg
create mode 100644 articles/stripe-integration-react/api_test_keys.jpg
create mode 100644 articles/stripe-integration-react/dashboard.jpg
create mode 100644 articles/stripe-integration-react/final_output.jpg
create mode 100644 articles/stripe-integration-react/hero.jpg
create mode 100644 articles/stripe-integration-react/index.md
create mode 100644 articles/stripe-integration-react/paymentflow.jpg
create mode 100644 articles/stripe-integration-react/paywithcard.jpg
If the upstream and master have no changes to merge , Already up to date. message will be printed on your Git Bash. These changes are committed to your local repository,
git checkout master
Output
Switched to branch 'master'
Your branch is ahead of 'origin/master' by 25 commits.
(use "git push" to publish your local commits)
Push these commits to publish them to your remote repository.
git push
And you are done. Refresh your remote repository, it will be up to date with the upstream.
We have forked, cloned, our repository is up to date, plus we are ready to work on our contributions. Before you submit your contributions, make sure you work on your changes and your content is well formatted ready to make a pull request.
Submit contributions using GitHub desktop
For convenience, open GitHub and open the repository with your preferred text editor.
If you are using Visual Studio Code, your cloned folder should look similar to this
Since we are trying to make our contributions to Section, navigate to the articles folder.
Create a folder to work with.
Add your contributions (i.e. index.md, hero image, and other media where necessary).
When you are done adding all your content, you now need to commit the changes to your remote GitHub repository. Launch your GitHub desktop and you will be able to see the changes you have added.
It is now simple from here, create a branch that will have your changes.
Since we have our changes ready, we need to merge these changes to the branch we have created. i.e. “the changes on your folder and your work in progress will follow to the new branch” and click switch to branch.
Publish the branch to your remote GitHub account and make sure you add a commit message as the summary.
Your branch content is on your remote GitHub repository, and you need to create a pull request to the origin repository to contribute your changes.
The create a pull request button will redirect you to your GitHub account where you now need to create a pull request. Make sure your title is relevant to the content you want to publish. Write a comment in the comment box with brief details of your content.
Once the pull request button is hit, you are done, you have submitted your contributions successfully.
Wait for your content to be reviewed and if any further changes are needed, a comment will be left by the reviewer suggesting possible changes you should make under your pull. Make your edits on your text editor and make a commit to update the changes and remember to have a summary of the commit you are making for better referencing.
Submit contributions using Git bash.
Since you have a clone available on your local computer, start working on you contributions using a text editor. Format your content according to the guidelines of the original repository.
Once you are done and ready to publish the content, it is advisable to push your changes under a branch and not to the master repository. This will help you to work and contribute changes under different topics without branch or merge conflicts.
When the content (topic) is ready, create a branch and make sure you checkout on the branch as it will hold all your changes you are working on. Open GitHub local directory on Git Bash.
If you run
git branch
OUTPUT
* master
All the branches you have created will be printed, in this case we have master branch, which is the current checkout. Create a new branch, with the name relevant to the topic or the content you want to push.
git branch <branch name>
git branch my-first-contributions
The new branch has been created. To confirm if the new branch was really created, run
git branch
OUTPUT
* master
my-first-contributions
Checkout the new branch you have created
git checkout <branch name>
git checkout my-first-contributions
OUTPUT
Switched to branch 'my-first-contributions'
All the available changes that you have made will be directed to the branch on the checkout. To check the changes you have created/modified run
git status
OUTPUT
On branch my-first-contributions
Untracked files:
(use "git add <file>..." to include in what will be committed)
articles/new-folder-name/
nothing added to commit but untracked files present (use "git add" to track)
These changes are available on the local repository, and you need to make them ready to be pushed to your remote. To do this, run
git add . (make sure the fullstop after git add is included)
Run to confirm the changes are ready.
git status
On branch my-first-contributions
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: articles/new-folder-name/hero.jpg
new file: articles/new-folder-name/index.md
Your file changes will be highlighted green, meaning ready to be published to remote. These changes are ready to be committed
git commit -m "my first contribution"
[my-first-contributions 6b5e391] my first contribution
2 files changed, 1 insertion(+)
create mode 100644 articles/new-folder-name/hero.jpg
create mode 100644 articles/new-folder-name/index.
Push to the branch
git push origin my-first-contributions
Your content is now on your remote forked repository. To share your contributions to the team, you need to make a pull request. Go to your GitHub account, under your forked repository.
Click the compare and pull request button.
And you are done. Wait for your content to be reviewed, make changes where necessary and your pull request will be merged to the team project.
Note: every time you are making new contributions, ensure your remote fork and the local repository are up to date.
Conclusion
The outputs highlighted on this article may not directly match to what will be printed to your Git Bash as that depend on the commits already published when making a clone or updating a clone as well as the file changes you have made.
References
How to clone GitHub repository
Peer Review Contributions by: Nadiv Gold Edelstein