developer toolbox

We’ll start by reviewing the typical Git workflow based on pull requests, then discuss some problems you might run into with a “typical” repository setup, and finally explain the details of preparing the Insoshi Git repository for collaboration.

Why Pull Requests?¶

Git was originally developed by Linus Torvalds to host the Linux kernel, and pull requests are the de-facto standard for submitting contributions in Git because that’s what Linus does. (He talked about this in his Google Tech Talk on Git.) The concept of the pull request is straightforward: You notify someone that you’ve made an update via email, messaging on GitHu*b, etc. and let them know where to find it. They can then *pull in your changes and merge it with their work.

Except for that interaction, everyone works within their own repository and on their own schedule. There’s no process waiting to be completed that blocks you from moving on to whatever you need/want to do next. And you’re not forcing anyone to drop what they’re doing to right now to handle your request.

It’s all very polite. And it works well in the context of distributed development since you avoid all kinds of coordination issues.

What’s needed?

1. 1. A publicly accessible repository where your changes can be found
2. 2. A local repository for your development

Even if you’re new to Git, these both seem like pretty straightforward things to do—especially if you’re using GitHub for the public repository: your repository is just a fork of the main project repository.

Let’s set up our repository by going to the official Insoshi repository and clicking on the fork button:

• Official Insoshi public clone URL: git://github.com/insoshi/insoshi.git
• My fork’s private clone URL: git@github.com:long/insoshi.git

Your local repository: The “obvious” thing to do¶

At this point, I’ll be tempted to go ahead and make a local clone of my fork:

$ git clone git@github.com:long/insoshi.git

and immediately get to work.

Technically, there’s nothing wrong with that. And as an individual developer starting a new project, it’s what you do, but there are several disadvantages to this seemingly straightforward approach. One of the major benefits of a distributed version control system like Git is that each repository is on an equal footing; in particular, we would like every fork to have the same master branch, so that if the “official” Insoshi repository should ever be lost there would be plenty of redundant backups. We also want it to be easy for each developer to pull in changes from the official repository; the “obvious” approach isn’t set up for that. Finally, it’s a bad idea in general to work on the master branch; experienced Git users typically work on separate development branches and then merge those branches into master when they’re done.

• Keep the repositories in sync so that each contains the full “official” repository
• Allow developers to pull in official updates
• Encourage working on branches other than master

• There’s no local connection to the official repository for updates
• There’s no mechanism in place to push official updates to my fork on GitHub
• We’re working directly on the master branch

Your local repository: The “right” way¶

Keeping the big picture in mind, here are the commands I’ve run to set up my local repository (using the GitHub id long):

$ git clone git://github.com/insoshi/insoshi.git
$ cd insoshi
$ git branch --track edge origin/edge
$ git branch long edge
$ git checkout long
$ git remote add long git@github.com:long/insoshi.git
$ git fetch long
$ git push long long:refs/heads/long
$ git config branch.long.remote long
$ git config branch.long.merge refs/heads/long

Let’s take a detailed look at what these steps accomplish.

So what does it all mean?¶

1) Step one¶

Create a local clone of the Insoshi repository:

$ git clone git://github.com/insoshi/insoshi.git

You should note that the Git URL for the clone references the official Insoshi repository and not the URL of my own fork (i.e., the clone URL is git://github.com/insoshi/insoshi.git instead of git@github.com:long/insoshi.git). This way, the official repository is the default remote (aka ‘origin’), and the local master branch tracks the official master.

2) Step two¶

I have to change into the repository to perform additional git setup:

$ cd insoshi

3) Step three¶

Insoshi also has an ‘edge’ branch for changes that we want to make public but may require a bit more polishing before we’d consider them production-ready (in the past this has included migrating to Rails 2.1 and Sphinx/Ultrasphinx). Our typical development lifecycle looks something like

development -> edge -> master

I want to create a local tracking branch for it:

$ git branch --track edge origin/edge

4-5) h3. Steps four and five

As I mentioned before, I’m resisting the temptation to immediately start working on the local ‘master’ and ‘edge’ branches. I want to keep those in sync with the official Insoshi repository.

I’ll keep my changes separate by creating a new branch ‘long’ that’s based off edge and checking it out:

$ git branch long edge
$ git checkout long

By the way, you can actually combine the two commands if you like, using just the ‘git checkout’ command with the -b flag:

$ git checkout -b long edge

You can name this branch anything that you want, but I’ve chosen my GitHub id so that it’s easy to identify.

I’m starting my changes off of ‘edge’ since that contains all the latest updates and any contribution I submit a pull request for will be merged first into the official Insoshi ‘edge’ branch to allow for public testing before it’s merged into the ‘master’.

7-8) Steps six and seven¶

I’m finally adding the remote reference to my fork on GitHub:

$ git remote add long git@github.com:long/insoshi.git

I’ve used my GitHub id once again, this time as the remote nickname.

We should run a fetch immediately in order to sync up the local repository with the fork:

$ git fetch long

8) Step eight¶

I’m pushing up my new local branch up to my fork. Since it’ll be a new branch on the remote end, I need to fully specify the remote refspec:

$ git push long long:refs/heads/long

Steps nine and ten

Now that the new branch is up on my fork, I want to set the branch configuration to track it:

$ git config branch.long.remote long
$ git config branch.long.merge refs/heads/long

Setting the remote lets me just simply use

$ git push

to push changes on my development branch up to my fork

Setting the merge configuration is mainly for completeness at this point. But if you end up working on more than one machine (work/home, desktop/laptop, etc.), it’ll allow you to just use

$ git pull

to grab the changes you’ve pushed up to your fork.

http://github.com/guides/Home

http://github.com/guides/keeping-a-git-fork-in-sync-with-the-forked-repo

Using git submodules to track plugins feed

Submodules allows you to manage subparts of a project in different git repositories and reference them in a “superproject” repository. Here is a link with a great example of submodule usage to track your plugins:

ovo je episode 1 (free) from pragmatic programmers github screencast

napomena: movie player (totem) neće ovo da reprodukuje kako treba (ubuntu 8.04 i 8.10) , vlc 0.9.x fino reprodukuje screencast (8.04)

http://pragprog.com/screencasts/v-scgithub/insider-guide-to-github

    * Episode 1: Getting Started (34 minutes)

      This episode will get you up and running with GitHub so that you’re comfortable with the general day-to-day tasks. You’ll learn how to:
          o clone a public project
          o create a new account
          o generate an SSH key
          o import an existing Subversion repository
          o create a new repository
          o fork a repository
          o push changes to a repository
          o create a private repository
          o add collaborators to a private project
          o clone a sub-module
          o collaborate with other users
          o send a pull request
          o merge changes from a pull request
          o watch projects and people
          o use project wikis
          o generate RubyGems
          o allow project donations

    * Episode 2: Advanced Tasks (40 minutes)

      This episode takes you beyond the basics so you can take advantage of time-saving tools, advanced GitHub features, and pro tips. You’ll learn how to:
          o save a ton of time by using the GitHub gem to create, clone, fork, and fetch changes
          o use the GitHub API to query commits, run searches, and get user information
          o configure a post-receive URL to notify an external service
          o create a simple Rails application to handle commit notifications
          o use the hidden API that generates the GitHub participation graph
          o create and delete branches and tags
          o deploy code from a GitHub repository to a server using Capistrano
          o delete and rename repositories