Getting Git for the Complete Beginner
You’ve decided to get involved with open-source and contribute to your first project. Great! But when you head over to the GitHub page, you’re a little confused. Git? Pull requests? Forking? Branching? It’s a new language to learn, especially if you come from a non-developer background.
This is an orientation for the total beginner to the landscape of Git. It contains the need to know terms, big picture concepts, and resources to continue learning. Of course, it’s also important to join an open-source community with a culture that offers mentorship and guidance for new contributors.
What is Git?
Git is a free, open-source version control and source code management software. Its primary purpose is to manage asynchronous contribution and version control for software developers. With version control, you have a time machine to go back to a project at any moment in the timeline. With asynchronous contribution, multiple people can work on the same project from their local machines simultaneously, anywhere in the world.
The range of open-source projects using Git is vast. The top 50 GitHub projects of 2020 are a small example. Not all ways to contribute on Git are coding or developer-based either. Almost all open-source projects are in need of contributors for documentation. A project I’m involved in as a writer is The Good Docs. They create free templates and resources for documenting open-source projects.
Git vs GitHub vs GitLab
Many platforms offer Git as a service. GitHub and GitLab are the top two you’ll likely use as a contributor. They host public Git project repositories and for the average user, offer the same general functionality. This source extensively breaks down the niche differences between the two.
Using Git: The CLI or UI
The average computer user likely only interacts with Graphic User Interfaces when using software. However, Git is primarily used through the Command Line Interface (CLI). The CLI is a program that uses text-based commands to execute tasks. You type these commands into a terminal or shell UI.
Figure 1. Windows Terminal
Figure 2. CLI and GUI Pros and Cons
So which should you use? It doesn’t have to be entirely either-or. They are two different and valuable tools to add to your workflow. If you’re doing more than the basics, you’ll likely encounter something that requires using the CLI. Knowing how to use both ensures you’re never left stuck.
If you want to learn more about using the CLI, GitLab offers a comprehensive guide and a handy cheat sheet.
Understanding the Fork-Branch Workflow
The most common workflow you’ll encounter in public-facing, open-source projects is the fork-branch workflow. This is true whether you’re contributing code or documentation. There’s a lot of information out there on how to technically execute this using Git. But if you’re a true beginner, you first need to understand what you’re doing and why. Keep in mind to always read a project’s contributing guide first to know which method they’d like you to use.
Accessing
Let’s say you’ve identified that the README file of a project needs updating. The first step of the workflow is accessing the project files the proper way. Forking a repository creates a copy of the original on your server, under your GitHub/Lab username. Cloning your forked repository then makes a local copy on your computer. However, your forked version is a snapshot of the project in time. To pull updates to your local copy and keep it current as you work, you must manually establish a remote connection to the original repository.
To get the files you’ll work on locally:
Fork the desired project’s remote repository.
Clone the forked repository to your local machine.
Add the original remote upstream to your cloned copy.
Figure 3. Forking, cloning, and adding the remote upstream
Vocab:
repository (repo): where files are stored for a project, like a file folder on your computer. It contains all the project files and version history.
remote repository: the files hosted on a Git service like GitLab or GitHub
local copy: the files on your computer.
fork: a copy of a remote repository under your username on GitHub/Lab
clone: the local copy of your forked repository on your machine.
remote upstream: a connection from your local copy to the original remote repo that will fetch updated information downstream to your local copy.
2. Working
It’s time to begin making your changes on your local copy. But you can’t just dive into editing the files in your clone. All work in Git is done in branches. You create a new branch in your cloned copy where you work on your feature. Since you’re updating the README, you create a branch called “readme-update-3.0”. As you work in the branch, you make commits to save your changes.
To make changes to the project files:
Create a new branch in your local copy where you will work
Commit your changes in your working branch
Figure 4. Branching in the local copy
Vocab:
branch: a copy of the repo’s main branch where you work on a certain feature. Changes do not affect the main branch. Given an identifying name
main branch: the original branch of a repo
commit: saving your changes in the branch
3. Contributing
Once you’ve completed the work in your branch you are ready to submit your contributions. Your previously forked repo allows you to push your branch from your local clone to the forked copy. From there, you create a pull request that lets the administrators of the original repo know you want to integrate your branch into the original repo. If the project administrators approve your request, the changes in your branch are merged into the main branch of the original repo. The README file on the official repo would reflect your new updates. In some cases, the admins might have feedback or changes, and you’ll have the opportunity to revise.
To add your contributions to the repo:
Push your branch to your forked repository.
Create a pull request to the original repository.
Have your pull request approved to be merged to the main branch in the remote repository.
Figure 5. Pushing upstream
Vocab:
pull request: a pull request communicates that you would like to merge a branch to the original repo from your forked copy. Admins review your request and make sure it is ready to be merged into the project’s main branch. Also called a merge request on GitLab.
push: move your branch upstream
Time to Practice
What is covered here is very simplified, and Git is very complex. But once you understand the jargon and process of Git for open-source, learning how to do it becomes much easier. The next step is practice. The following are great resources to put this information to use.
The open-source project Learn Git Branching is a tool to help visualize and practice basic to advanced uses of Git in the CLI.
This guide shows you which commands to execute in the fork-branch workflow.
If you want to learn more in-depth information about this workflow and others used on Git, read BitBucket’s helpful guides.
Good luck and happy branching!
by Megan Albert