# git revision control

## Introduction to git

You can browse the LDP github repository via the web at https://github.com/tLDP/.

Using git offers many advantages over other version control systems, but between git and github there's a few features that make it well suited for a distributed and diverse set of contributors:

- Each user can have their own independent and up-to-date copy of the repository and modify it.

- Submitters do not need to have write access to the main repository to submit updates

- Using github relieves TLDP staff of managing account requests

- Ability to import changelogs from other VCS, so you can track changes going back about 16 years or more

These advantages come a bit a bit of a price in terms of increased complexity. There's a lot to git, but we'll cover enough here to manage documents in LDP.

You can get an account on github by going to their website and signing up for a free account. For ease of use, you may want to use SSH keys to authenticate with github otherwise you will be asked to enter your password with each update.

If for some reason you are unwilling to create a github account, we will do our best to accomodate you. You can use `git clone https://github.com/tLDP/LDP.git` to make a copy of the repository locally on your system. Make your proposed changes and then you can use `git diff > myhowto.patch` to generate the differences between the original and your updates. Send an e-mail to discuss@en.tldp.org that you have updates you'd like to submit outside github and a volunteer will help you out.

## Setting up git on your local Linux system

Many different systems run git, but this document will focus on doing as many functions from the Linux command line as possible

You will need to make sure that `git` is installed on your system. It isn't always installed by default so you may need to add it using your package manager such as `yum` or `apt-get`

## First time git setup

The first time you start using github you'll need to run some commands

- Clone the entire repository (about 400 MB) with: `git clone https://github.com/tLDP/LDP`

- Go to the LDP repository on github and click on `Fork`. This will create your own copy of TLDP in your space that you can write to.

- Lastly, link your local repository with your repository on github with `git remote add upstream git@github.com/MyGithubID/LDP.git`

## Submitting changes to TLDP

Each time you make changes to TLDP you'll need to go through this process. It'll make sure that your changes are submitted for review and if approved, automatically added into TLDP

- Create a new branch using `git checkout -b MyNewBranch`

- Start making your changes, either editing files, or creating new ones. You can use `git diff` to see changes between what you have locally and what the last checked in repository is.

- If you added new files, you will need to use `git add filename` to indicate that there are new files for git to manage.

- Now you commit the changes locally using `git commit`. This creates a new revision and drops you into an editor to add a comment for the changes you've made. You can include the `-m` option and a string to do this at the command line.

- Now you need to push your changes into your forked repository on github with `git push -u upstream MyNewBranch`

- From the github website, you will need to create a push request using your branch.

Once the push request is accepted, you can remove the branch using `git branch -D MyNewBranch`