How to work with pgAdmin's Git repository

The PostgreSQL source tree is now managed with Git. pgAdmin did also its move to Git a few weeks before. With a great help from Magnus, I try to learn this really cool tool. Here are some tips to create patches for pgAdmin using Git. And you can surely use this to create patches for PostgreSQL and Slony too.

Grab the repository

First thing to know, we have a mirror on github, which makes things quite easy. They have a great UI and some interesting features that I'm sure you don't want to miss. But you should know that it's not required and you can clone the repository directly from git.postgresql.org. This post will only show the github way, but I think you can figure your way from this post anyway.

You need to create an account on github. You can have one for free if you want to work on open source projects. Here is the link: https://github.com/signup/free. You simply need to enter a username, a password, and a valid email address. I don't think there is anything else to do. You should be able to connect right after that. Next step involves that you enter your SSH public key in your GitHub profile, so that you can push commits into your git repositories over there.

Once this is done, you have to fork the pgAdmin Git repository on github. Yeah, right, fork. Not the project, but the repository Follow this URL: http://github.com/postgres/pgadmin3. You'll be at the pgAdmin mirror. Then, click on the "Fork" button (if it's disabled, then you're not logged in – so, first log in, and get back here). It'll take a few minutes before you actually have your pgAdmin Git repository on GitHub.

Once this is done, you don't really need your browser. Get back to your terminal session.

You'll need the Git command-line tool. So, install the right package for your distro, or grab the Git Windows installer and execute it.

Once the git command is installed, you can clone your GitHub repository:

(of course, you should replace "gleu" with your username on GitHub... this is also true for the other commands we'll see in this blog post)

On my laptop, it takes 3 minutes to clone the whole repository. When I say "whole repository", I really mean it. You've got all the repository history in your local drive. Right now, it gives me a 181MB directory.

First patch with Git

Now that you have cloned your GitHub repository, what can you do? work on a patch for the 1.12 branch? OK, let's do that. First, we need to switch to the 1.12 branch (its real name is REL-1_12_0_PATCHES):

Now, we can work on the code? not really. You should not change the "official" branches. Well, you can do, but it's not the recommended way of dealing with Git. You need to create your own work branch. So, here it goes:

guillaume@laptop:~/pgadmin3$ git branch mybugfixwork

This command creates the "mybugfixwork" branch from the "REL-1_12_0_PATCHES" branch at the currently checked out point. Now, we need to get into our new branch:

When you're happy with your changes, you have to ask git to record them. Before doing any commits, you first need to add every changed and new files to the git index. Let's assume I made some changes to pgadmin/frm/frmStatus.cpp. I'll add this file to the next commit with this command:

guillaume@laptop:~/pgadmin3$ git add pgadmin/frm/frmStatus.cpp

If you don't remember which files you changed, you can always use "git status":

Once all new and modified files are added to the git index, you can commit your work:

guillaume@laptop:~/pgadmin3$ git commit

An editor will open with the list of added and modified files. You can enter your commit message. Once you quit the editor, the commit is done. If you don't want to open an editor, you can still use the "-m" option with your commit message right after this option, just like you did with the cvs and svn commands.

(once again, lazy people like me would prefer the "git commit -a" command because it does the "git add" command on all modified and removed files, and the "git commit" all in one command, but you would still need the "git add" command for new files)

All of this happens in your local repository. Nothing happens on github yet. You can do as many commits as you want. When you want to push your commit(s) to github, you'll have to do a "git push". As we never pushed this new branch, we'll also have to specify:

(lazy people like me tried once the "git push --all", and felt usually sorry right after... because it pushed all branches, even ones you don't want to push... happened to me when I was writing this )

The new branch is now on your GitHub pgAdmin repository.

Sending your patch

You want to let the commiters of pgAdmin know about your great patch? No problem. You have usually two ways to do it. The easier one is to send an email to the pgadmin-hackers list to let them know about your repository and in which branch is your patch (here, it is "mybugfixwork"). Otherwise, you can send them a real patch. Git makes that easy for you. When you did the commit, the first output line was this one :

[mybugfixwork b4f9cda] Add a stupid comment.

The hash in front represents your commit. You need to find the hash of the previous commit :

guillaume@laptop:~/pgadmin3(mybugfixwork) $ git log --format=oneline
cd3d7a65628c85f648638489409ebb435b0e8fe4 Add a stupid comment.
55e9b5cae1060da39be3a77f181bf413157d6dc3 Fix an issue with tab keypress on frmQuery.
bc16a495cdd43e4ac23d35cbce19d6a8522d1000 Cast the transaction ID to text so we can sort on it in the
...

In my example, the interesting hash is the second one, aka 55e9b5cae1060da39be3a77f181bf413157d6dc3. Now, I can ask git to create a patch file:

Commentaires

If you are going to send patches by email, the Github step is completely unnecessary. You just have to clone the official repository, commit your fix (in a branch of any kind) and use `git format-patch`.

I'm just saying that because II know that some people are scared, for whatever reasons, to use services like Github, and your post looks like it's a mandatory step to provide patches to pgAdmin, whereas they don't require it at all most of the time.