Introduction
This guide introduces the basics of using Git. Git is a tool that helps you track and manage changes when working on writing or documentation projects. Whether you’re starting a new project or contributing to an existing one, Git gives you a way to save your work in clear steps, collaborate with others, and stay organized over time. In this guide, you’ll learn how to:
-
Set up a Git project from scratch or work with an existing one
-
Make changes, save them, and share updates through GitHub
-
Keep your files in sync when working with teammates
-
Contribute to shared projects by submitting edits for review
What Is “Docs as Code”?
“Docs as code” means treating documentation with the same tools and processes developers use to write software. Writers use plain text formats (like Markdown), version control systems (like Git), and collaborate via platforms such as GitHub.
This approach helps technical writers:
-
Track changes
-
Work closely with developers
-
Improve the editing process
-
Contribute iteratively
Pre-requisites
Before starting, ensure you have the following:
-
A text editor or Integrated Development Environment (IDE) of your choice (e.g. Visual Studio Code)
-
A GitHub account. If you do not have one, you can create an account at GitHub.com
Setting Up Your Project Repository
(To contribute to an existing project, skip to "Forking a Repository".) To begin, you need to set up your project repository. Setting up a new repository involves creating a new repository on GitHub and cloning it to your local machine. Cloning to a local repository gives you a working version of code or documentation to make edits, test ideas, and draft revisions without altering the source material. Follow these steps:
1. Go to GitHub and create a new repository. Make sure to initialize it with a README file.
-
Select the "New" button in the repositories section
-
Fill in the repository name and description
-
Choose visibility (public or private)
-
Select "Create repository"
2. Clone the repository to your local machine using the command:
git clone <repository-url>
3. Navigate to the cloned repository directory:
cd <repository-name>
4. Open the repository in your text editor or IDE (Visual Studio Code).
When do you clone?
-
When you start working on a new project you’ve created
-
When you fork someone else’s repository and want a local version
-
When you're collaborating and need a personal working environment
Forking a Repository
If you are contributing to an existing project, you may need to fork the repository first. Forking a repository means to create your own copy of the repository on GitHub you can make changes without affecting the original project. To fork a repository:
1. Go to the repository page on GitHub.
Note: Ensure you are on the main page of the repository you want to fork.
2. Click on the "Fork" button in the top right corner.
3. Select your GitHub account as the destination for the fork.
4. Clone your forked repository to your local machine using the command:
git clone <forked-repository-url>
5. Navigate to the cloned forked repository directory:
cd <forked-repository-name>
6. Add the original repository as a remote to keep track of changes:
git remote add upstream <original-repository-url>
When do you fork?
-
When contributing to someone else’s open-source project
-
When building on a template or tutorial
-
When customizing a shared resource privately
Making, Committing and Pushing Changes
Once you have your repository set up or forked, you can start making, committing, and pushing changes. To commit means to save a snapshot of your project at a specific moment. Each commit has a unique ID and a short message explaining the changes that were made. To push means to send your committed changes from your local project to the version stored on GitHub (or another remote repository).
1. Open the file you want to edit in your text editor or IDE.
2. Make your changes to the file.
3. Save the file locally (CTRL+S).
4. Stage the changes for commit using the command:
git add <file-name>
Or to stage all changes:
git add .
5. Commit the changes with a descriptive message using the command:
git commit -m "Your descriptive commit message"
6. Push your changes to your forked repository on GitHub using the command:
git push origin <branch-name>
|
Important
|
Do this as many times as you need to while working on your project. Each time you make changes, repeat the steps of staging, committing, and pushing. |
When do you commit?
-
After editing a file
-
When completing a task or fixing an issue
-
Before switching focus to a new section of your project
When do you push?
-
When you want to share changes with your team
-
When you want to back-up your work online
-
When you’re ready to submit changes for review
-
When you’ve resolved an issue
Pulling Changes from the Original Repository
If you are working on a forked repository, it’s important to keep your fork up to date by pulling from the original repository and merging with your local project. To pull means to fetch the latest updates from a shared repository and merge them into your local project. To merge means to combine changes from one branch to another. Follow these steps:
1. Ensure you are in your forked repository directory.
2. Fetch the latest changes from the original repository using the command:
git fetch upstream
3. Merge the changes into your local branch using the command:
git merge upstream/<branch-name>
4. If there are any merge conflicts, resolve them in your text editor or IDE.
5. After resolving conflicts, stage and commit the changes as shown in the previous section.
6. Push the updated branch to your forked repository on GitHub using the command:
git push origin <branch-name>
When do you pull?
-
When you need to catch up on group changes
-
When you need to integrate changes
-
When you want to avoid overwrite issues
When do you merge?
-
After reviewing a collaborator’s pull request (see below)
-
When incorporating changes from the original repository
-
Before publishing a unified version of the project
Creating a Pull Request
Once you have made changes to your forked repository and pushed them, you can create a pull request to propose your changes to the original repository. A pull request is a formal request to merge your branch into another, usually the main project. Follow these steps:
1. Go to the original repository on GitHub.
2. Click on the "Pull requests" tab.
3. Click on the "New pull request" button.
4. Select the branch you want to merge from your forked repository.
5. Review the changes and add a descriptive title and comment for your pull request.
6. Click on the "Create pull request" button to submit your pull request.
When do you make a pull request?
-
When your contribution is ready for review
-
To initiate collaboration, discussion, or feedback
-
When you believe your changes are ready to merge with the main branch
Conclusion
This document has provided an overview of the Git workflow, including setting up a project repository, forking a repository, making changes, committing, pulling changes, and creating a pull request. By following these steps, you can enjoy the benefits of using Git for version control in your technical writing projects:
-
Tracking revisions across drafts and documents
-
Collaborating with contributors without overwriting each other’s work
-
Reviewing and reverting changes
-
Testing updates on isolated branches
-
Archiving work with transparency and traceability
-
Preventing data loss
Remember to regularly pull changes from the original repository to keep your fork up to date and to communicate clearly in your pull requests.