Health Checks: Commits

Health Checks: Commits

This category of health checks focuses on the code you check into your GForge Next project, how it relates to task management, team and file sizes.

Commits Per Tracker Item

Definition: The number of separate commits associated to each Tracker Item in your project. Only commits created in the last 90 days are used, so the trends will change over time.

What it means: Having too many commits makes it harder to understand the associated Tracker Item’s history later on. It can also skew Sprint, Burndown, and Release metrics to look bigger or smaller than they really are.

How to fix? Although you can add or remove associations between a commit and a Tracker Item, it’s better to look forward than try to change history. When planning a Sprint or Release, consider the size of each Tracker Item, and break them down into smaller tasks that might affect fewer files, or involve fewer iterations for each TI.

Commits with Tracker Items

Definition: The percentage of commits in the last 90 days that are associated (or not) to a Tracker Item. Also checks for commits that are tied to more than on TI.

What it means: Pushing commits without an associated task is an easy way to mess up your code base over time. It’s also bad for team collaboration and Sprint and/or Release tracking.

How to fix? To fix existing commits, you can create Tracker Items, and associate them using the SCM Commits listing. Click a commit and use the “Tracker Item Associations” section at the bottom of the commit details view.

You can (and should) also fix the process for pushing commits to your project:

  1. Go to the Project Admin SCM tab, and choose “Require” for the “Associate Tracker Items” option.
  2. You might also check the “Restrict Tracker Item Associations” setting, depending on whether you want to allow associations between commits in this project and Tracker Items from other projects.
  3. Usually, this setting should be “Yes” to keep it to the current project.


Definition: The number of users with commits in the last 90 days, and the proportion of all commits made by each user.

What it means: For smaller projects (with only one or two contributors) this check won’t mean much. For full-sized Agile teams (4-5 contributors) or larger, traditional teams (10 or more contributors), this check can help you understand if work is balanced properly between team members.

How to fix? If you’re not using Tracker Items (and requiring that commits tie to them), then you should start right away. Having a specific task should be required in order to make code changes anyway, and an official task list lets the Product Owner, Scrum Master, or even the team itself to balance tasks among contributors by size, functional area and dependencies. Proper task balancing will lead to balanced commits from the team.

Files Per Commit

Definition: The number of files changed (or added, or removed) by each commit. Only commits created in the last 90 days are used, so the trends will change over time.

What it means: In general, commits should touch less than ten files. Large commits (many files and/or many lines of code) are harder to review, harder to understand later, and more likely to cause merge conflicts with other commits.

How to fix? This is another one where what’s done is done. Going forward, make sure that the team is doing proper analysis on task sizes during planning, and on the changes to be made when working each task. If a specific task requires changing many files, try to find a way to iterate on it, changing a few files in one commit, reviewing/merging that commit, then moving on to the next set of files.

Of course, sometimes you’ll just need to bite the bullet – a breaking change in a dependency/library, an urgent security fix, etc. But those hefty commits should be the exception and not the rule.

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.

Screenshot from 2022-10-24 19-28-23


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:

Screenshot from 2022-10-24 19-34-26

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.

Screenshot from 2022-10-24 19-54-15

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:

Screenshot from 2022-10-24 19-41-13

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,

Screenshot from 2022-10-24 20-11-02

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

Screenshot from 2022-10-24 20-11-19

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

Screenshot from 2022-10-24 20-11-57

Integration with GForge trackers

You may have noticed this section in the Information page:

Screenshot from 2022-10-24 20-14-24

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.

Screenshot from 2022-10-24 20-19-39


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!