Complete the git handbook

scor I and contributed these pages already which can be adapted/updated:

http://drupal.org/node/551858
http://drupal.org/node/707484

plus someone else contributed this one:

http://drupal.org/node/288873

subscribing to make me remember to come back :-)

Created a new (temporary) Git prototype book: http://drupal.org/handbook/git

Please move the relevant stuff there. Bojhan contributed a nice "TortoiseGit" page.

After reading http://drupal.org/node/711070 I found it odd that branching for bugfixes/features and subsequent merging are not mentioned as a workflow in the guide anywhere. Instead there's a workflow around rebase.

Wasn't this cheap branching one of the advantages of common DVCSes?

@Heine: yep, that's mainly because we need to have a consensus, and it seems like we already have one. All that discussion started on Personal sandboxes/repos/branches for issues for git and end up in three work-flows detailed in A detailed description of the work-flows after we implemented phase 3.

I suppose the plan is to integrate them to the manual when d.o modules have those functionalities

I did some editing and added a Mac git client page. Planing on doing a bit more work on this prototype Git documentation in the next weeks.

tagging

I've just started a SmartGit (Windows Git GUI) handbook page, needs work.

I'm not sure if this is the right place to discuss this, so feel free to redirect me. Should we break up the "Clients and GUI tools" into a couple sections like this:

Installing Git on your system
--Git on OS X
--Git on Windows
--Git on Linux
----Git on Ubuntu
----Git on Fedora
Clients and GUI tools
--GitX (Mac)
--SmartGit(Win)
etc....

It just seems that the first step in all of the various Client and Gui pages is going to be "Install Git," which we only need to explain once per OS.

@SeanBannister - SmartGit is cross-platform.

@bryan kennedy: I'd +1 that organization of the information, your reasoning is sound

There are a LOT of different GUI clients out there - some standalone, some not, some cross-platform, some not, and certainly not all of them have the intention of being a fully-featured interface to the git world. IMO there should be a page that tries to roughly group these into categories based on the different things/levels of use people may have. Such a page should probably not be written until we've gotten documented, or at least listed, all the clients that are out there, though...

@sdboyer: Can't believe I missed that SmartGit is cross-platform. Very cool. I've fixed up the guide but someone else will need to include the install instructions for Mac and Linux.

I think (1000% sure) we should write something about using eclipse with git.
A lot of developers are using eclipse to create and apply their patches in cvs.

After some searching I also found an official git tool for eclipse based on jgit ==> egit.

If someone else got more experience with this it would be awesome to get a handbook page about that.

There is already a complete user guide on their website: http://wiki.eclipse.org/EGit/User_Guide
We can link to that. We only need to say what we have to fill in on this page: http://wiki.eclipse.org/EGit/User_Guide#Cloning_Remote_Repositories

Can we do that?

Something like http://en.wikipedia.org/wiki/Comparison_of_integrated_development_enviro..., perhaps...

Also, I would like to add a quote from http://drupal.org/about/authoring:

General information about web development, products, tools, software languages, standards, practices, techniques etc is considered out of scope unless the topic provides additional information which is specific to the Drupal environment. For example, a general tutorial on using CSS would be out of scope, whereas a discussion of how to work with CSS within a Drupal theme would be very much in scope. A procedure for installing Eclipse would be out of scope, whereas a procedure for configuring Eclipse for Drupal development work would be in scope.

(emphasis added by me)

Because it looks like there is A LOT of documentation out there about Git (and especially about how "strange" git is, compared to $oldvcs... ;)

I like #11, but it really should boil down to a list of links elsewhere on the web, IMHO...

Or maybe just a link to https://git.wiki.kernel.org/

EDIT: This is about using Eclipse/EGit in response to #15.

I got as far as entering

git://git.drupalcode.org/projects/drupal.git

This let me retrieve a local clone (without any authentication).

However, I was unable to authenticate with my CVS password in order to connect to one of my contrib modules.

Is password authentication not supported? How can you convince EGit to use key authentication?

Re-prioritizing as critical. We can't launch without documentation for the people affected by this change.

How about for real this time?

Moving projects.

Maybe a git bisect tutorial?

I started a wiki page on the migration group: status of git handbook, but sadly unordered lists breaks badly :-(, well I copy that here to, but I definitely think this should be a wiki page to trak it better.

• (0%) cvs - git | Introduction
  • (0%) cvs - git | Graphic illustration of CVS
• (0%) cvs - git | Usage policy
  • (0%) cvs - git | 3rd party libraries in Drupal CVS
  • (0%) cvs - git | Why Drupal CVS access is on a per-project basis
• (0%) cvs - git | CVS FAQ
  • (0%) cvs - git | How do I change my CVS password?
  • (0%) cvs - git | Why drupal.org doesn't host GPL-"compatible" code
  • (0%) cvs - git | Why is Drupal still using CVS (How can I help in the move to Git?)
  • (0%) cvs - git | Troubleshooting common CVS problems
    • (0%) cvs - git | How do I delete a directory from CVS?
    • (0%) cvs - git | Resolving a 'sticky tag is not a branch' error
    • (0%) cvs - git | Resolving a 'sticky tag is not a valid branch in this CVS repository' error
• (0%) cvs - git | CVS clients and GUI tools
  • (0%) cvs - git | Command line CVS
  • (0%) cvs - git | Cervisia (Linux/Unix)
  • cvs - git | CVL (Mac)
  • (?%) cvs - git | GitX (Mac) (new)
  • (0%) cvs - git | CvsGui [WinCVS] (all platforms)
  • (?%) cvs - git Eclipse CVS plug-in (all platforms)
  • (0%) cvs - git | SmartCVS (all platforms)
  • (0%) cvs - git | TortoiseCVS (Win)
  • (?%) cvs - git | TortoiseGit (Win)
  • (0%) cvs - git | Zend Studio Configuration for CVS
• (0%) cvs - git | Our code repositories for core and contrib
  • (0%) cvs - git | Checking out from the main repository
  • (0%) cvs - git | Checking out from the contributions repository
  • (0%) cvs - git | Breakdown of a typical CVS command
  • (0%) cvs - git | Checking out a copy of each branch of the contributions repository
  • (0%) cvs - git | rsync Drupal CVS repositories
  • (0%) cvs - git | CVS over ssh
• (0%) cvs - git | Drupal CVS branches and tags
  • (0%) cvs - git | Overview of core branches and tags
    • (0%) cvs - git | Overview of contributions branches and tags
    • (0%) cvs - git | List of core branches and tags
    • (0%) cvs - git | List of contributions branches
• (?%) cvs - git | Other CVSGit resources
  • (0%) cvs - git | Rolling a new Drupal core release
• (?%) cvs - git | Git reference guide for module maintainers (new)
• (?%) cvs - git | Git reference guide for site builders (new)

WOW! Thanks for compiling that, Marco!

I'm pretty sure only a handful of those pages are actual launch-busters. Crucially:

- Introduction to Git
- Usage policy, all the legal stuff (should hopefully not be hard to "port")
- FAQs (except the "how to help move to git" one. ;)). We particularly need some info on common problems people will run into and how to solve them. Hopefully our beta testers can provide some of the fodder here.
- The Quickstart guide (which I don't see listed here), since this is probably 99.9% of our traffic to this section of the handbook.
- CVS to Git cheat-sheet (which I don't see listed here), to help people making the switch.
- Clients: Just command line and SmartGit (cross-platform GUI). The rest can filter in from contributors as needed.

That's it. If we get more than that, then awesome. But I think we can launch with this set. If someone disagrees, feel free to chime in. :)

It might also be helpful to have a doc page addressing git terminology. When I first switched to git I was very confused as to why checkout didn't work as expected, like svn.

I'd suggest rethinking the naming of these. Checkout != clone.

• (0%) cvs - git | Our code repositories for core and contrib
  • (0%) cvs - git | Checking out from the main repository
  • (0%) cvs - git | Checking out from the contributions repository
  • (0%) cvs - git | Breakdown of a typical CVS command
  • (0%) cvs - git | Checking out a copy of each branch of the contributions repository
  • (0%) cvs - git | rsync Drupal CVS repositories
  • (0%) cvs - git | CVS over ssh

I've gotten the Introduction to Git into a functional rough-draft. This intro is slightly different than what is found in the CVS handbook as it incorporates the introductory material form the CVS handbook title page, and Introduction (some of which was redundant). I've also broken the sections about contributing code out into their own page (on the Git Handbook outline wiki), since that topic doesn't really fit as an intro (IMHO). I have included the tree analogy from the CVS Intro, with minor changes relevant to Git (mostly this was dropping the term "branch tag").

This page could use a fact-check; at the very least, to make sure that the distinctions made between the various concepts are correct.

Moving to the docs queue

Well the above doco will be great, some simple step by step how-to's are really needed for a selected sub-set of the git clients. It will be the first time using git for many. Ideally covering:

For developers:

- Creating a new project, starting from nothing bar installed client with 0% configuration
- Cloning, local modification and pushing these back
- New branch / tags and switching (or the git equivalency of this)

General:

- Cloning and working on an issue, and creating a patch

Personally, I do not think that I will have time to learn git while on the road, meaning any 5min critical issue will be ignored for the time being (4 more months). But if I can see how to do the basics in 15min, then I'll be more likely to try :)

As a pre-migration issue, I'd say this is done. All of the topics above are covered somewhere (or were at the time of the migration)