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.

These settings apply your name and email address to changes you make using git:

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

Many users find that coloring certain output from git makes that output easier to read and quickly understand. Apply these settings as well:

git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

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

Branches

Distributed SCM like git encourage the practice of branches very frequently. Typically, one of the first things a user does after retrieving a repository is to make a new branch. Any work done on this branch can very easily be applied back to the canonical source on what is usually called the master branch.

To see that you are currently on the master branch, do this:

cd release-notes
git branch

You should see the following output:

* master

The master Branch
Never work directly on the master branch unless there is a very good reason to do so. Always make a new branch and work on it instead.

To make a new branch, use this command with a branch name of your choice:

git branch my-new-branch-name
git checkout my-new-branch-name

Notice that the git checkout command is not quite the same as what you may be used to for CVS or SVN. In those SCM systems, a checkout retrieves the repository content from the canonical source. In this context, git checkout switches branches. (It has other capabilities too, but they may be too confusing to mention at this point, so they are not covered here.)

Basic Editing

Source Explanation
This document does not cover DocBook XML or other explanations of Fedora Documentation content. Refer to the Documentation team pages if you need help.

Just as the concept of a checkout changes in git, so does the concept of a commit. When you commit a change, you are recording it in the index of the repository you're currently using -- usually on your local system. Later, you use a push command to send one or more commits back to the canonical repository, if there is one. (You can always make a git repository locally and simply use it there, never needing to push anything.)

First, make sure that you are not on the master branch:

git branch

Once you are satisfied, make a change. Then commit that change on your current branch:

git commit -a

The -a switch automatically adds any new files that you made. An editor appears (vi by default, or the value of your $EDITOR environment variable if set) containing a log of the changes that are being committed. Examine the log to ensure it is correct. Then type a commit message in the editor starting at the top of the log.

Typically, your message should be a single line summary. If you need to add detail, put in a blank line after the summary, and then write details as needed. The git program is capable of generating email from these commits that you can send to projects if desired. When you observe these standards, the email is very readable by the upstream project maintainers.