Git for docs writers
I have heard from several would-be documentation contributors that they don't know how to effectively use Git to contribute to Fedora documentation. This document attempts to provide some guidance. It is intended to be opinionated to keep from overwhelming the reader.
To do anything else on this page, you'll want to have the following:
- A Fedora Account System (FAS) account
- git (
dnf install git)
- The text editor of your choice
- Basic terminal experience
- (recommended) Podman (
dnf install podman)
Before your first edit
When you first get started, you won't have commit access to the git repos for docs. You'll need to create your own copy, called a "fork". To do this,
- Go to the Pagure repo you want to fork (for example https://pagure.io/fedora-docs/quick-docs/)
- Click the Fork button at the top.
This creates a fork under your account (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs). Now you need to "clone" your forked repo—download it to your computer.
- Click the Clone drop-down menu in Pagure
- Copy the contents of the SSH box
- From a terminal, run
git clone <SSH URL>. For example:
git clone ssh://email@example.com/forks/bcotton/fedora-docs/quick-docs.git
Now here comes the part where you make your life—and the life of the other contributors—a little bit easier. You're going to add the official repo as another "remote" so that you can keep your fork in sync.
- From a terminal, run
git remote add upstream <UPSTREAM URL>. For example:
git remote add upstream https://pagure.io/fedora-docs/quick-docs.git
Before every contribution
Before you start making your contributions, you want to make sure you're up-to-date with the upstream repository. This means you are making changes to the latest version.
- Ensure you're in your master branch with
git checkout master
- Get the upstream changes with
git fetch upstream
- Merge the upstream into your repo with
git merge upstream/master
Making a contribution
Now it's time to make the contribution you came here to make. You'll want to start by creating a new branch to do the work in.
git checkout -b branch_name(where branch_name is something like
Now you can make whatever changes it is that you want. Fire up your favorite text editor and edit away. When you're done, it's time to commit the changes.
git add file(s) that you edited
- Edit the commit message and quit the editor. If your system uses vim as the default editor (which it probably does, unless you changed it), type
ito enter editing mode. When you're done writing your commit message, hit the Escape key, type
:wq, and hit enter.
Finally, it's time to push your changes from your local machine to the remote server and create the pull request.
git push origin branch_name
- In your web browser, go to your forked repo (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs)
- Follow the git forge's instructions for creating a pull request (docs for Pagure and GitHub)