A Git cheat sheet For Server Documentation Authors

Peter Boy (pboy) Last review: 2025-11-07

The sources for the Fedora Server documentation are stored and managed in a Git repository. This is not commonly practiced by authors and therefore its usage is unknown or not well known and not routine. Authors only need a fraction of Git’s functionality to manage documents. Here we compile the most common work steps and describe their Git counterparts.

This is work in progress

Prepare your local workspace

Usually, you mirror the central remote Server documentation sources on your local workstation and work on the various documents locally. When done, you copy them back to the central remote storage.

In Git terminology this is a clone of the repository.

Create a local subdirectory where the files of the documentation should be stored, and make it to your default. We use fedora-server-docs in your home throughout this guide
```
[…]$ mkdir ~/fedora-server-docs
[…]$ cd    ~/fedora-server-docs
```
Clone the Server documentation sources into your default working directory
```
  […]$ git clone https://forge.fedoraproject.org/server/user-documentation.git ./
```
Check the result:
```
[…]$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
```
Git does "tag" or name the cloned repo as clone of the remote repo "origin". It is the default for any action you perform with the cxentral remote repository. You can check further details.
```
[…]$ git  remote -v
origin	https://forge.fedoraproject.org/server/user-documentation.git (fetch)
origin	https://forge.fedoraproject.org/server/user-documentation.git (push)
```
With fetch, you apply all changes in the central repository to your local workspace. Do this regularly to stay up to date.

With push, you incorporate your changes into the central remote repository. Only members of the Server WG can do that.

Prepare your remote storage space

Upon completion of your work, you will want to copy the content back to the central remote repository. Due to QA processes, only members of the Server WG can write directly to the central remote repository. Everyone else must create their own area in which to store their changes.

In Git terminology this is a fork of the repository.

Open the Server User Documentation repository in your browser and log in with your FAS account.
In the upper right corner you see a button "Fork". It opens a form to set the properties of your fork. Accept the default values unchanged, with the exception of the optional Description field. Select the button "Fork Repository" to create the fork.
The fork becomes the active window. Right arom the center you see a blue button "HTTPS" besides the address of your forck and a button to copy the URL.

Isolate work on new or updated items in a separate area

Such a separate area is named a "branch" in Git. It is a temporary space, copied mostly from the main branch and where you work on a specific document independently from modifications on other documents in the repo, usually for a longer period of time. All changes you make in this branch will be merged back into the source branch after completion.

Ensure, that the main branch is your currently active branch

[…]$ mkdir ~/fedora-server-docs
[…]$ cd    ~/fedora-server-docs

Delete a Branch no longer needed completely locally and remotely

TBD

Working on content

Check if you are on the branch you intend to work on
```
[…]$ git branch
* main
stg
{sometext}-upd
```
If not, switch to the branch you want to use.
```
[…]$ git checkout [stg|main|{sometext}-upd]
```
Git will adjust and modify the content of your working directory accordingly!
Before your begin to work update your working directory
```
[…]$ git
```
Modify content
Update preview and check:
```
[…]$ ./docsbuilder.sh
```
Preview in your browser using the address 'localhost:8080
Repeat step 4 & 5 as required.

Save Your Work

Commit your work locally

Check status
```
[…]$ git status
```
Add files to commit stage as appropriate
```
[…]$ git add <FILENAME>
```

Commit locally

[…]$ git commit -m "<YOUR COMMIT MESSAGE>"

Forgot a file in the last commit

Add a file to the last commit without modifying the commit log message

Add the file (or several files) to the staging area
```
[…]$ […]$ git add <FILENAME>
```
Add it to the last commit
```
[…]$ git commit  --amend  --no-edit
```

You can also add a files and replace the commit log message

Add the file (or several files) to the staging area
```
[…]$ git add <FILENAME>
```

Add it to the last commit

[…]$ git commit --amend -m "an updated commit message"

Save your work in the central remore repository

Transfer your work into the central remote repository

Only members of Server WG can do this.

[…]$ git push origin [main|]

Save your work in your fork

[…]$ git

[…]$ git push origin [main|{sometext}-upd]

Invite to discuss your work

Finally publish your work

Merge a branch into main

Resolve a merge conflict

Miscellaneous

Copy an article from one branch into another

Not recommended

Sometimes you may need an article located in onother branch in youre current work branch. An easy way is just to copy it. But be aware, this way you don’t get related files, e.g. images, in one go! You have to check for file dependencies and copy one by one.

First check, if you are in the intended branch and then copy the file from another branch

[…]$ git status
[…]$ git checkout <other-branch-name> <file-or-dir>

as an example

[…]$ git status
On branch main
Your branch is up to date with 'origin/main'.

[…]$ git checkout gui-upd modules/ROOT/pages/usecase-gui-addon.adoc

„Cherry-pick“ a commit from another branch into your current branch

The recommended alternative to copy

TBD

„Cherry-pick“ a commit from a forcked repo into your current branch

TBD

Compare the same file in different branches

TBD

Want to help? Learn how to contribute to Fedora Docs ›