git support in GForge

Note: If you’re looking for git support in GForge AS, up to and including 6.4.5, please contact GForge Support for assistance.  Documentation for GForge AS is being retired in favor of the current product.

GForge Next provides full support for the git SCM (Source Code Management) tool, in addition to SVN and CVS.

Unlike SVN and CVS, git is a distributed tool where each user has a copy of the full repository in his or her machine. The basic workflow of git involves committing changes against the local repository and sharing the changes via pull and push operations.

Since commits in the local repositories cannot be “seen” by the GForge server, GForge sets up a global, centralized (“bare”) repository where the changes can be pushed to.

Setting up your project for git

To enable git support for your project, you need to be a project administrator. In the Project Admin tabs, select “Modules”, make sure that “Code Repository” is turned on, then select “git” as the SCM tool.  Click the “Save Changes” button at the bottom of the modules list to update the project.

 

Note: Changing the “Code Repository” setting does not delete any existing repository.  The GForge Next UI shows only the active SCM type.  Also, switching from git to svn and back to git only re-connects the existing git repository.  Nothing is deleted!

Once the repository is created, you will see the empty repository in the Git section:

If you repository is brand new (empty), you’ll see the friendly prompt above, with no data.  Let’s change that by adding data to your git repository.

git Basics

First, let’s take a small detour to talk about git as a tool.  There are lots (and lots and lots) of git commands, and you should be familiar with the basics before tackling the rest of this walk-through – or have a GUI tool that handles the nuts and bolts for you.

GForge Next includes some links to helpful information about git.  You’ll also notice the “Get Support” button in the screen shot – don’t hesitate to get in touch with any git-related question, whether it’s specific to GForge Next or not.

Cloning git Repositories

The first step in using your project’s git repository is to clone the repository.  Every team member who wants to contribute to the repo will do this as well.  The information you need is located on the Information tab, in the “Access Your Repository” section:

Depending on the site and project settings, your repository might be available via HTTPS (by default) or SSH. 

Note: If you have an existing repository, it’s actually even easier to get started.  Go into the directory for the existing repo, change the “origin” remote to the URL in GForge Next (with git remote set-url origin <newURL>), and do a “git push” to get everything moved in.

Copy the command from the text box and run it on your own computer (from a terminal, Command Prompt window or add the URL to your favorite git GUI tool).  After this, you’ll have a new directory to work in, containing, well, nothing – yet.

Adding the initial data

At this point, the git repository is empty and is not very useful, so let’s add files, create a commit, and push that commit to your GForge Next project repository.

First, you’ll need to checkout a branch, or in this case, create one.  Do git checkout -b main to create the default branch that git expects for new repositories.  You can use any name you want, but almost all git repositories have a main branch, so it’s useful to observe this convention for others coming to the project.

Create or copy any file you need (e.g., README) into your local copy of the repository (the directory created by the git clone command, earlier), then use git commit -a -m 'First commit!' to create the commit.

Note: The words ‘First commit!’ are completely up to you.  There’s no conventional first message for git.

When you’ve built up one or more commits like this, you can push them to the repository, using git push origin main.  After a successful push, you’ll see data in the Information tab Activity chart,

the new commit(s) will be listed in the Commits tab next to Information,

and the changes you’ve pushed will now be visible when you browse the repository.

Integration with GForge trackers

You may have noticed this section in the Information page:

Using the square-bracket notation in your commit messages (or in your branch name!) allows GForge Next to connect the code changes in your repository to the tasks that caused them.  This integration goes both ways – you’ll see links to Tracker Items in the SCM Commits list, and you’ll see the list of related commits in the details for each Tracker Item.

In the Project Admin SCM tab, you’ll also find settings to ignore, allow, or require references to Tracker Items, as well as some similar settings that can be helpful in managing developer workflow, security, and audit.

Setting up Access Control Lists

The Access Control Lists (ACLs) provide fine-grained permissions control in the source code repository, allowing you to specify read and write access for the different users in your project to different branches in the repository.

Note: This works differently in git than for Subversion, because git branches are physically separate from paths, whereas Subversion branches are paths in the repository.  Subversion ACLs are path-based because all repository users will share the same directory structure.

To view or edit the ACLs for your project’s git repository, go to Project Admin, and click the “SCM” tab.  You’ll see two more tabs open under it: “Settings” and “Access Control List”.  You can add or remove branch names from the list, and change the access level for each role in your project.  Users will get the highest access level across any roles they might have.

Conclusion

That’s enough to get you started using git in GForge Next.  Of course, there are many more features, settings, and workflow options available to suit your process and team’s needs.  Don’t hesitate to submit a ticket using the “Get Support” button with any git or GForge Next-related questions.

Happy git-ing!