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.
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.
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
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 firstname.lastname@example.org
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
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:
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://email@example.com/git/release-notes.git
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:
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.)
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:
Once you are satisfied, make a change. Then commit that change on your current branch:
git commit -a
-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.