User:Pfrields/Drafts/Git for Docs Contributors

The distributed source code management system  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.

= 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, 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  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  package. Use this command to do that:

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

Set Global Configuration for Git
Git supports a  file that holds some of your global settings. You can edit this file by hand, or you can use the  program.

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

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  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
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  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

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  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,  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 =

Just as the concept of a checkout changes in, 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  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  switch automatically adds any new files that you made. An editor appears (vi by default, or the value of your  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  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.