Writing code can be daunting, but with the right support and tools in your hands, it does get easier. Case in point: GitHub.
GitHub brings coding experts and teams together in a single collaborative platform, where they can share ideas and methods to develop amazing software together.
This Nira guide will give you a step-by-step tutorial to use GitHub, as well as discuss how you can eliminate common Git problems while working.
Let’s start with a quick GitHub tutorial so you know how to use the platform.
1. Create a GitHub Account
First and foremost, you’ll need a GitHub account.
Click here to create a free account and start using the platform right away. If you’re still in the GitHub for Beginners stage, signing up for a free account is a good place to start. You get to enjoy access to unlimited public and private repositories, plus there are tons of features, including project management and bug tracking, to ensure seamless workflows.
That said, keep in mind you can only allow three collaborators for private repositories on the free version.
2. Install Git
You can’t have GitHub without Git.
Wondering what Git is? It’s a version control system developed by Linus Torvald, the programming icon, who created it to easily track changes to source code changes.
Git allows programmers to effectively collaborate, coordinate work, and work together on complex code and development projects by tracking changes and helping teams work remotely on large-scale programs.
Therefore, the next step is to install Git on your computer. To do this, click here.
3. Create a Repository
You must know how to start a repository to use GitHub effectively.
A repository, also known as a repo, is just like your regular “projects.” It’s a place where you can store everything related to a specific project, such as files, spreadsheets, data sets, images, videos, and so on.
To create your own repository, click on New Repository in the upper right-hand corner of your screen. Follow this by naming your repository and adding a brief description of the project.
Check the Initialize this repository with a README box. Lastly, select Create Repository.
Note: We highly recommend including a README file within a repository that has all specific information regarding any given project. On GitHub, you can add a README file as soon as you create a new repository.
4. Create a Branch
When building software, you will find yourself dealing with multifaceted projects and handling different versions of a program. GitHub’s branching feature enables you to edit multiple unique versions of your repository simultaneously.
Branching allows you to work on multiple different “branches“ to make edits before you commit them to the master branch. To start a new branch in GitHub, go to your new repository and click the drop-down that reads Branch: Master.
Type a branch name (Eg: ProjectName-edits), and click on Create branch.
When we start a new branch, you get a copy of the master branch until you edit it to make new changes. A branch generally goes through many steps and approvals before it is eventually merged into the master branch. In addition, branches are also ideal for adding new features or fixing bugs.
5. Create and Commit Changes to a Branch
Let’s take a look at how you can make changes to a branch in Jupiter.
Go to the code view of your newly created branch. Select the file you want to change, and then click on the pencil icon in the upper right-hand corner.
Edit the file as you want. Follow this up by describing the changes you made by writing a commit message. Click on Commit Changes.
Each saved change is known as a commit, and every individual commit will have its own commit message that comprehensively explains why a specific change was done in the first place. Commit messages are useful as they show the entire history of changes and help project contributors understand how the project has changed over time.
6. Open a Pull Request
Developers must open a pull request to merge their branch with another person’s branch. Think of a pull request as GitHub’s way of notifying relevant parties about a request to incorporate changes into the master branch.
A pull request shows the differences in red and green, making it easier for everyone involved to understand the changes between the branches. You can make a pull request as soon as you complete a commit.
To open a pull request, open the Pull Request tab and click on New Pull Request.
In the Example Comparisons box, locate the branch you created and compare it with the master branch. Cross-check whether you’re okay with the changes and then click on Create Pull Request.
Name your pull request and describe the changes you made. When done, click on Create Pull Request again. For prompt feedback, use the ‘@‘ feature to notify the people from whom you want feedback before sending a pull request.
7. Merge Your Pull Request
It’s possible you may need to pass on your phone request to your superiors to merge it with the master branch. However, if you have the liberty to merge your full request yourself, here’s what you need to do:
- Select Merge Pull Request followed by Confirm Merge.
- Delete the branch you just merged after it’s incorporated into the master branch.
That’s how you use GitHub and create awesome software in collaboration with other developers and the members. While it may feel complicated at first, once you get a hang of it, it’ll get easier. GitHub has seriously simplified coding—all you need is a little hands-on practice.
Common Problems When Using GitHub
You can make mistakes when working on GitHub. We are human beings, after all. But not rectifying these mistakes can result in loss of information or incorrect information.
Below we’ll discuss some of the more common GitHub issues and their fixes.
GitHub Authentication Fails
If you face difficulties pushing your remote branch in GitHub Desktop, there might be a problem with SSH.
For starters, try logging out of GitHub Desktop via Preferences. If this doesn’t help, switch to the command line and try to push manually. For example: git push –set-upstream origin second-kafka-pr-for-issue-1123
If this command prompts you for a passphrase, you can confirm your SSH was somehow confused. Things should go back to normal upon entering your passphrase.
If your build is failing and you’re having trouble understanding the reason, check for the following:
- Front matter. See if there are any apostrophes and colons in front matter fields. If yes, surround them with quotes to fix problems
- Indent in the nav fields
- Missing closed brackets or tags
- Image file names, such as wrong capitalization, images with encoded values (like %)
- Poorly formatted image links
If you know the reason behind the error, troubleshoot it further with the yarn verify-mdx path/to/file.mdx command. Entering this command will give you more information about the error, including the specific character and line number causing the error.
404 Error During Local Testing
Redirects can be a bit strange on local builders, which is why you should test them.
To do this, go to the page that is being redirected and wait until it shows a 404. Once you see the error sign, wait for about 1 to 2 minutes again. This will redirect you after a while. If it doesn’t, cross-check whether you’re set up the redirect correctly.
You can also test redirects out in the Gatsby build as well.
Merging conflicts can’t seem daunting, but it simply involves choosing between two different versions of a dog. Below are some tips to help you troubleshoot merging conflicts:
- Try to fix your merge conflict as soon as possible, especially if you’re working on taxonomy changes. Having your branch linger on for even a little while will make it outdated from the develop fast, which, in turn, can result in unexpected issues.
- Check your fix locally to locate errors.
- Ask your PR approver to review your PR after fixing the merge conflict.
To resolve merging configs, you have two options:
- When you see the conflicts in GitHub Desktop, select the option to resolve these in VS Code.
- Use the GitHub website editor, where you select Resolve Conflict to fix the conflicts.
Failed ‘Build the Docs Site‘ Build Check
‘Build the docs side“ build check can fail. If this happens after your local builds have been built successfully, you might have to force a rebuild of the cache.
Here’s how to go about it:
- Find the gatsby-config.js file in your local depot. Use CMD-P to jump to it fast in VSCode.
- Swipe the first line of code with the second line. Unless you make the Gatsby Build check rebuild the cache, it doesn’t matter what order these lines are in.
const fs = require(‘fs’);
const parse = require(‘rehype-parse’);
- Save the file and commit the change to your repository.
- Re-run the build checks.
This should reset the build check, but you’ll have to wait for a long time.