User:Pfrields/Drafts/Git for Docs Contributors

The distributed source code management system git has quickly become very popular in Linux. It is tremendously powerful, with features far outstripping those in CVS or Subversion (SVN). It can also be a little daunting for people who have either never used source code management (SCM), or are very used to the different (and relatively primitive) functionality in CVS and SVN.

This document explains how to get started, without involving aHowtoll the stuff you don't need to know.

Required Skills
This tutorial assumes you are comfortable opening and using a terminal. If you aren't, you may not be ready to work on documents controlled through SCM. You can still participate by helping edit on this wiki -- refer to Help:Editing for more information.

Concepts

All SCM systems are more or less based on the same ideas. Many people can retrieve a local copy of the files, make changes, and send the changes back to be included in the canonical repository so others can receive them.

The way that a distributed SCM changes this routine is by removing some of the "special-ness" of the canonical repository. Your local copy of the files is just as full-featured as any other copy, including the one on a central server where everyone has agreed to put their changes. You can "send" your changes to your local repository, and then later push them up to the canonical location.

Imagine you took a long plane trip for eight hours. Before you leave, you retrieve a copy of the repository files on which you want to work. Using a conventional SCM, you can make changes to these files, but there is no easy way to have a series of changes to a single file become a series of pushes (or "commits"), when your plane lands again and you connect back to the canonical source. Changes to a single file are recorded as one big change.

With a distributed SCM like git, you actually send your changes little-by-little to your own repository copy during the plane ride. Each is shown separately in exactly the way you intend. When your plane lands, and you connect back to the Internet, you can push these changes back to the canonical repository and they are recorded in the correct order and scope.

Conflicts sometimes can happen with any SCM, but not only is git much smarter about how these are managed, but it offers a lot of flexibility and features for avoiding them.

First Steps

Install Git Packages

The easiest way to install everything you might want or need for git is to get the git-all package. Use this command to do that:

su -c 'yum -y install git-all'

Set Global Configuration for Git

Git supports a ~/.gitconfig file that holds some of your global settings. You can edit this file by hand, or you can use the git-config program.

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Get the Files

Setup Account, SSH, and Certificate First
The following steps assume that you have set up a Fedora account, your SSH keys, and a certificate. For more information refer to this page.

Visit the Fedora Hosted git repositories and find a document on which you want to work. They should be marked as "Fedora Documentation" in the description field. Some examples are:

• Release Notes

Move to a suitable working directory. To retrieve a local copy of a repository, use the following command, which creates a subdirectory to store the files.

git clone ssh://username@git.fedorahosted.org/git/release-notes.git