Document process for switching branches in Git Instructions

I think this is a good idea (I'm amorfati on IRC). A couple of quick points:

1. I already mentioned in IRC, but for posterity: it should be git branch -a instead of git branch -r. git branch -r only shows remote branches, not all available.

2. git creates remote tracking branches based on what it cloned from the remote repository. So the local branch names are always the same as the remote branch names after a clone, which is why git can automagically create the tracking. Otherwise, you need to create it manually and specify the names of both the local and remote branches to track. But for most people (and for the purposes of the cheat sheet), git clone should be assumed as the first step, so there won't be a need to manually create tracking branches at all.

3. I think the big thing to remove is the -b argument from git checkout. That's just incorrect, especially after the use of git clone.

4. I'd also question the use of git rebase in creating patches, as that's some pretty heavy git wizardry that's generally only needed for edge cases. I presume someone thought that out and there's a good reason, but it's a thing that even git masters argue about how to use correctly, and not something you'd generally put in a cheat sheet targeted towards total newcomers and people who don't want to think about how to create a patch (like me). withdrawn for now

(removed a bunch of requests for info that's already there for maintainers)

After discussing it in IRC, I withdraw point 4 until a later date, so it's all good.

A point about tags; checking out a tag isn't something you can contribute on: you need to check out a branch (same as CVS). I wonder if it's necessary to even mention checking out tags in the cheat sheet. We don't mention it in the CVS instructions.

Checking out from tags is a great idea when deploying code for a real website, not for doing development. So, I think that warrants a few lines on the Git instructions tab, since that's targeting a lot of possible audiences: maintainers, developers, contributors, users, etc. So, +1 to leaving that in there.

Where's the issue about the patch instructions? I, too, think we're trying too hard to optimize for maintainers here, and throwing possible contributors into this multi-step rebase process is going to be really scary. I'd keep going, but I know I'm off topic for this thread. ;) Therefore, a link to the right place to discuss it would be much appreciated...

Cheers,
-Derek

Hmm, I suggest we change `git branch -a` to `git branch -r`. That gives us just the remote branches that CAN be set up with corresponding local branches. After that, we split the commands into 2 sections like, "To see all remote branches, do a git branch -r" and then, "To set up a local branch to correspond to a remote branch, do a git checkout BRANCHNAME".

Thoughts?

We were discussing this in IRC, and we're going to have a problem either way with the instructions as it stands now.

If you do git branch -a, you get a listing like:

7.x
6.x
remotes/origin/5.x
remotes/origin/4.0.x
....

If you do git branch -r, you get a listing like:

origin/7.x
origin/6.x
origin/5.x
origin/4.0.x

In either case, valid branch names for git checkout are everything after origin/. So the instructions tell you to do something bad if a remote tracking branch hasn't already been created, namely git checkout remotes/origin/7.x or git checkout origin/7.x depending on which command you run. Doing so will create a detached HEAD.

At least with git branch -a, the user has a chance of checking out the correct branch should the user already have checked it out correctly, since the local branches are at top.

We should figure out a way to clarify what the branch names are before settling on which version of git branch we should use.

Set back status.

Two things: I posted the following which I hope will be helpful as we work on docs:
http://groups.drupal.org/node/129069
It's a place for larger questions of focus and audience.

In the context of that post, I'm planning to resolve this by removing tags from Git instructions and asking someone to update http://drupal.org/node/1066342 with a better explanation of when branching a tag is appropriate.

Also, I'm inclined to git branch -a

done.