Git for docs writers
Some would-be documentation contributors may not 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.
This is one way, not the only way. The instructions in this document are not the only way to accomplish the goals. In some cases, they may not even be the best way, but they're a way that works. This is targeted explicitly at beginning git users, and so does not include much in the way of choices or options. As you get more familiar with git, you may deviate in ways that work best for you.
To do anything else on this page, you'll want to have the following:
A https://fedoraproject.org/wiki/Account_System[Fedora Account System] (FAS) account
git (`dnf install git`)
The text editor of your choice
Basic terminal experience
Podman if you use a Linux OS such as Fedora (`dnf install podman`) or Docker CE if you use macOS.
While this document was written with Fedora in mind, the steps below work on any operating system with git installed. See the https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[git documentation] for more information on installing git on other operating systems.
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".
You will need to keep your fork up-to-date with the official repo. This is covered later in this document.
By default, `git clone` will clone a repository into a subdirectory named the same as the repo that exists in the directory you run the command from. In order to keep your filesystem nice and tidy, you may want to have a dedicated directory that you keep all of your docs repos in. For example: `$HOME/fedora/docs`
Go to the upstream Pagure repo
Click the '''Clone''' drop-down menu in Pagure
Copy the contents of the '''Git''' box
From a terminal, go to the directory you want to keep your repository in. For example `cd $HOME/fedora/docs`. You will need to create this directory if it doesn't exist (for example: `mkdir -p $HOME/fedora/docs`)
From a terminal, run `git clone -o upstream <GIT URL>`. For example `git clone -o upstream \https://pagure.io/fedora-docs/quick-docs/`. **Note: do not forget `-o upstream`. That's really the essential "trick" of this workflow.**