[pacman-dev] Git guide for pacman

[Dan McGee]

I put this together last night and today to help everyone out with GIT
usage. It is meant to be a overview, not a "step-by-step type exactly
what I say" type of thing. Let me know if it is helpful, unhelpful,
and what needs to be made more clear. I don't want to make it much
more
complex then this- once you understand the basics, you should start
picking up the power of git on your own.

-Dan

=================

Super quick GIT guide

This isn't meant to be an all-encompassing guide by any means- it is meant to
be a really quick walk-through on how to do some basic operations on the
pacman codebase in git, such as submitting a patch.

For more extensive tutorials, check out the following:
http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
www.kernel.org/pub/software/scm/git/docs/everyday.html
http://wiki.winehq.org/GitWine (talks a lot about maintaining patches)

In addition, all git commands have decent manpages to refer to. They can be
reached one of two ways- for the git-add command, type 'man git-add' or
'git help add'.


=Getting Started=

The first step with git is cloning a remote repository. This is known in the
CVS and SVN camps as checking out. GIT checkout has a different purpose, but
that will be covered later.

To grab the pacman source, run the following:
    git clone http://code.toofishes.net/gitprojects/pacman.git

This will check out a local copy of the repository for you. This means you have
the FULL history of the project on your computer, not just the most recent
revision. This allows you to get work done even when offline, for example.

The first steps after cloning may be just to look around. If you have read the
tutorials mentioned above, even if you do not understand everything in them,
you will be much better off.

You will probably want to set up your name and email address for use in commit
logs:
	git repo-config user.name "Your Name"
	git repo-config user.email "me at example.com"
If you pass the '--global' flag to the above commands, the name and email will
be stored in ~/.gitconfig, so will be used for all git projects unless
overridden by a setting in the individual project.

To update your local repository with any new branches, run 'git pull'.

=Next Steps=

'git branch' will show you a list of branches. Initially, master is the only
branch. However, if you pulled from a remote repo, you may have grabbed other
branches- these can be seen with 'git branch -r'. Read the manpage for details.

When working with git, it is good practice to never do your work on the master
branch. This should stay clean to allow you to run 'git pull' and ensure that
conflicts do not happen on the update.

To create your own working branch, do the following (naming it whatever your
heart desires):
    git branch working
    git checkout working
Or compress the above into one command:
    git checkout -b working
I highly recommend you read the man page for both of these commands.

'git-status' is highly helpful, read up on that too.

=Making a patch=

Woo! You found a bug in pacman (what a surprise) and know how to fix it. Ensure
you have your working branch checked out ('git checkout working'). Then edit
the file(s) you need in order to make your changes. Compiling is a good idea
to ensure your patch didn't break anything, and if it is a big change, running
'make check' is highly recommended.

So what do you do now? First, run 'git status'. You should see a list or even a
few lists of files. The descriptions by each are a bit confusing, but you
should be able to figure it out. GIT takes a different approach than CVS or SVN
to committing changes- it doesn't commit a thing by default. You have to tell
it what to commit, usually by running 'git add <filename>'. At this point, the
file in its current state will be sent to a staging area for the commit. If
you go back and change something in the file, you will have to git-add it again
if you want the changes to be reflected in the commit.

To commit your patch to your branch:
    git add <all edited files>
    git commit -s

When writing a commit message, keep the following in mind. The first line is
used as a patch summary- keep it short and concise. Next, skip a line and type
out a full description of what your patch does. By full, I don't mean long- if
you described everything in the summary line, then don't even bother with a
message. Finally, skip one more line and you will have your Signed-off-by.
This should have been automatically added by passing the '-s' parameter to
'git commit'.

There is one more important step before submission. Because git is distributed,
you don't have the most current version of the repository unless you go out and
get it. In the easiest case, this is just running 'git pull'.

You also want to make sure your patches are based off the most recent revision,
known as the 'head'. To do this, checkout your branch with your patches, and
use the following command:
    git rebase master
To visualize what the above command did, qgit can be very helpful.

To format a patch for email submission and review:
    git format-patch master
This command will format all patches that make up the difference between your
working branch and the master branch. They will be saved in the local
directory; to store them elsewhere read up on the '-o' option.

=Fixing your patch=

So you sent off your patch to the ML and you got a few suggestions back. How
does one fix it? Hopefully you did it on a branch and not the master branch,
otherwise you are going to have a much tougher time. :)

If it was the last patch on a branch:
    (edit the required files)
    git add <edited files>
    git commit --append -s

If it was deeper in your patch tree:
    (ensure you are in the branch you wish to edit)
    git checkout -b tmp HEAD~<number> (where number is how far back you want to
                                       go, use 'git log' to determine)
    git reset HEAD^
    (edit the required files)
    git commit -s -c ORIG_HEAD
    git rebase --onto tmp working~<number> working (replace working with your
                                                    current working branch)
    git branch -D tmp

http://wiki.winehq.org/GitWine has good information on the above, that is where
most of this came from. After fixing your patch, you will probably want to
rebase it as described above, and then use format-patch to submit it again.

=Further reading=

Commands you will definitely want to be knowledgeable on:
    clone (only once!), branch, checkout, status, pull, fetch, diff, add,
    commit, rebase, format-patch

=Helpful Hints=

'git' itself is a wrapper script that calls the other commands. Thus, git-add
can be called with either 'git add' or 'git-add'.

qgit in extra is a great GUI viewer for git repositories. In addition, read up
on 'git-instaweb'.

Keep typing 'git co' instead of 'git checkout'? Try this:
    git config --global alias.co checkout