141 lines
3.6 KiB
Markdown
141 lines
3.6 KiB
Markdown
# The CAcert policy repository
|
|
|
|
This repository contains work in progress policy documents for CAcert.
|
|
|
|
## Getting started using Git
|
|
|
|
We use [Git](https://www.git-scm.com/) for working with this repository. Git is
|
|
a free and open source distributed version control system.
|
|
|
|
### Installing Git
|
|
|
|
To work with Git you need a piece of client software. Git is available for all
|
|
major operating systems. On Linux systems Git is available from your
|
|
distribution's package manager and can be installed using something like
|
|
|
|
```shell
|
|
# install Git on Debian based systems
|
|
sudo apt install git
|
|
```
|
|
|
|
or
|
|
|
|
```shell
|
|
# install Git on Fedora based systems
|
|
sudo dnf install git
|
|
```
|
|
|
|
For Windows or MacOS you should use the binary installers from the [Git
|
|
Download Page](https://www.git-scm.com/downloads).
|
|
|
|
### First steps with Git
|
|
|
|
Open a Terminal window (Linux and MacOS have default terminal applications, on
|
|
Windows you might want to use the *Git bash* that comes bundled with the Git
|
|
client installation).
|
|
|
|
Tell Git who you are and what email address you would like to use. This
|
|
information will be put in commits you will do later.
|
|
|
|
```shell
|
|
# Tell Git who you are
|
|
git config --global user.name "Your Full Name"
|
|
git config --global user.email "yourname@cacert.org"
|
|
```
|
|
|
|
### Get a clone of this repository
|
|
|
|
A local working copy is called a *clone* in Git terminology. Run
|
|
|
|
```shell
|
|
cd $HOME/where-your-projects-live
|
|
git clone https://code.cacert.org/cacert/cacert-policies.git
|
|
```
|
|
|
|
to get your local copy.
|
|
|
|
### Update your local copy
|
|
|
|
If you have not worked on your copy for a while you can update it with the
|
|
following commands:
|
|
|
|
```shell
|
|
cd $HOME/where-your-projects-live/cacert-policies
|
|
git pull -r
|
|
```
|
|
|
|
### Making changes
|
|
|
|
If you want to make changes to the content of the repository, working on a Git
|
|
branch is recommended. You can have multiple branches in your local Git clone
|
|
and can switch between these.
|
|
|
|
```shell
|
|
cd $HOME/where-your-projects-live/cacert-policies
|
|
# create a branch for your work
|
|
git checkout -b some-topic-you-will-work-on
|
|
```
|
|
|
|
You can then make changes in the files in your working copy as you like. You
|
|
can also add new files. When you are satisfied with what you have, you can add
|
|
the changes to Git's staging area (in some documents this is also called the
|
|
*index*):
|
|
|
|
```shell
|
|
git add .
|
|
```
|
|
|
|
You can show the status of your local copy using
|
|
|
|
```shell
|
|
git status
|
|
```
|
|
|
|
If you would like to remove a file you can run
|
|
|
|
```shell
|
|
git rm the-file-you-do-not-want-anymore
|
|
```
|
|
|
|
To publish your changes for review you need to create a commit and push your
|
|
branch to the origin repository.
|
|
|
|
Please make yourself familiar with [how to write good Git commit
|
|
messages](https://cbea.ms/git-commit/). It will make the life of your future
|
|
self and of other contributors a lot better.
|
|
|
|
```shell
|
|
# Make a commit
|
|
git commit -m "Add inspiration quotes
|
|
|
|
Fixes #1"
|
|
# Push your branch to the origin repository
|
|
git push origin some-topic-you-will-work-on
|
|
```
|
|
|
|
You may repeat the edit, commit, push cycle multiple times and finally create a
|
|
pull request by clicking on the link in the output of the git push command.
|
|
|
|
### Switching to another branch
|
|
|
|
If you wait for a review on your pull request or want to work on a different
|
|
topic you can switch to the main branch and start a new branch from there as
|
|
described above.
|
|
|
|
```shell
|
|
git switch main
|
|
```
|
|
|
|
### Recommended reading
|
|
|
|
Git comes with a very comprehensive built-in help. Help can be retrieved using
|
|
|
|
```shell
|
|
# get help for Git as a whole
|
|
git help
|
|
# get help for a specific command, in this case git switch
|
|
git help switch
|
|
```
|
|
|
|
If you would like to dive deeper into Git you can read the free [Pro Git
|
|
book](https://www.git-scm.com/book/) on the Git website.
|