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 around the center, you see a blue button "HTTPS" besides the address of your forck and a button to copy the URL.
Add your fork to your remote repositories.

Choose a descriptive name. Some recommend the name “upstream.” That’s actually a bit misleading. “Upstream” usually refers to the project where the ultimate development of the project takes place. In the case of server documentation, that would be the central remote repository, not a fork, of which there are many. Maybe you should choose your username or simply “myfork.”
```
[…]$ git remote add {NAME} {URL}
```
As an example, if would use
```
[…]$ git remote add myfork https://forge.fedoraproject.org/pboy/user-documentation
```

Isolate work on new or updated items in a separate area

Working on a new article or on an update of an existing one, it is advantageous to work in a temporary space, copied mostly from the main branch, independently from modifications on other documents in the repo and without disturbing the main repo. It is especially useful, if you work on it for a longer period of time. All changes you make here will be merged back into the source, usually main, after completion.

In Git terminology this is a branch inside the repository.

Ensure, that the source, usually main, is your currently active branch
```
[…]$ git status
* main
stg
{sometext}-upd
```
Otherwise switch to main.
```
[…]$ git switch main
```
Update your local workspace
```
[…]$ git pull [origin]
```
The parameter is optional. The cloned repository’s main branch is usually the default.
Create a new branch und switch to it at the same time
```
[…]$ git checkout -b <NEW_BRANCH_NAME>
```
Alternatively you can also use
```
[…]$ git switch -c <NEW_BRANCH_NAME>
```

Delete a Branch no longer needed completely locally and remotely

Delete the remote branch

[…]$ git push -d <REMOTE_NAME> <BRANCH_NAME>

Delete the local branch
```
[…]$ git branch -D <BRANCH_NAME>
```

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 [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 remote 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 push {YOUR_FORK_NAME} [main|{sometext}-upd]

Invite to discuss your work

Create a Pull Request

TBD

Modify a Pull Request

TBD

Finally publish your work

Merge a branch into main

TBD

Resolve a merge conflict

TBD

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

'Cherry-picking' picks up a commit that was made in another branch and applies that very same commit to your current branch. As with the copy command about it copies files from one branch into another, but not just one file, but all files that were processed in this commit. With regard to documents, the text file of the document and all associated files such as images, etc. will be transferred in one go.

Check if you are on the branch you intend to work on

[…]$ git branch
* main
stg
{sometext}-upd
{othertext}-new

If not, switch to the branch you want to use.
```
[…]$ git switch {sometext}-upd
```

Skip through the log and finde the commit you want to cherry-pick

[…]$ git log
commit bdb3a418f523167b422099b742bcf6d61068770f (HEAD -> main, origin/main, origin/HEAD)
Author: Peter Boy <pb@boy-digital.de>
Date:   Sat Nov 8 10:43:12 2025 +0100

    Amended sections.

commit afe5fecff99300edb77b841eacd021bf6186edd4
Author: Peter Boy <pb@boy-digital.de>
Date:   Fri Nov 7 13:09:24 2025 +0100

    Initial commit of a Git Cheat Sheet for authors.

commit 29668a512ad66595a550aec08a1171e42f219d11
Author: Peter Boy <pb@boy-digital.de>
Date:   Thu Nov 6 15:40:09 2025 +0100

    Updated minutes 2025-11-05 meeting.

commit ac3d25fd1f6f7be2d05fe3d8d22d570ec77a5b35
Author: Peter Boy <pb@boy-digital.de>
Date:   Mon Nov 3 10:27:02 2025 +0100

    Updated minutes

Copy the commit hash to the clipboard

Cherry-pick the commit
```
[…]$ git cherry-pick [-x]  <commit-hash>
```
If you want to cherry-pick the minutes of the 2025-11-05 meeting of the above example, it would be
```
[…]$ git cherry-pick -x  29668a512ad66595a550aec08a1171e42f219d11
```
The abbreviated hash (the first 7 digits instead of 40), that you see in the overview in the web interface of the remote repository, too, is also sufficient. You may specify multiple commit hashes to cherry-pick multiple commits in one go.

The parameter "-x" is optional. It enables you to provide a standard commit message, so it might easier in the future to see, what you did and why.

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

Find the URL of the other fork or repo. In the Fedora forge Web interface click on the number right of the "Fork" button. You get a list of the currently existing forks. Select the one you want to cherry-pick and copy the URL into the clipboard.
Add the other repo to your remote repos. Choose a descriptive name, eg the username.
```
[…]$ git remote add {USERNAME} {URL}
```
As an example, if you want to add my fork
```
[…]$ git remote add pboys https://forge.fedoraproject.org/pboy/user-documentation
```
Fetch the branches
```
[…]$ git fetch  {USERNAME}
```
As above get the log of the other branch, find the commit you want to cherry-pick and copy the commit hash into the clipboard
```
[…]$ git log  {USERNAME}/{BRANCH}
```
Cherry-pick the commit
```
[…]$ git cherry-pick {COMMIT_HASH}
```

Compare the same file in different branches

TBD

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