Git Team

Mission statement

The Git team is responsible for building, maintaining and providing expertise on the Git version control system. Its main responsibilities include:

• Upstream development of the Git version control system.
• Provide expertise to other teams at GitLab.
• Foster the Git community.
• Ensure the long-term viability of the Git project.

Upstream development

The Git team is responsible for driving the upstream development of Git both in accordance with the goals of the community and to address GitLab-specific needs as raised by other teams. This falls into the following broad categories:

• Implementation of new features in the form of new tooling as required by use cases at GitLab.
• Scalability improvements in the form of optimizations and new data formats.
• Improvements to the usability of Git so that it remains the first choice for developers.
• Maintenance of the Git codebase.

Provide expertise

The Git version control system is at the core of what GitLab is doing and is thus of critical importance to many teams across GitLab. This doesn’t only include teams part of the Engineering division, but also spans across other divisions like for example Support. The Git team is the main contact point for such teams and provides expertise on how to use Git effectively and efficiently. It will provide insights into following non-exhaustive list of topics:

• How can a certain use case be implemented with Git?
• How to improve performance of certain workloads?
• How to expose certain features of Git to customers?
• What is happening in the Git community and what is the direction the project heads into?
• Which Git related workflows and practices should be encouraged among Git users?

Foster the Git community

GitLab relies on the Git community to be healthy. It is our belief that a healthy community is a community with diverse view points, including those views held by our direct competitors active in the same community. The Git team will help foster and grow the Git community:

• Ensure an influx of new contributors via mentorship programs like Google Summer of Code or Outreachy.
• Improve Git documentation and materials for new contributors.
• Attend or host community-oriented events like user groups or Git Merge.
• Help out community members by providing guidance and doing reviews.
• Spread information in the form of for example blog posts or Git Rev News.

Long-term viability

The Git project has been growing organically for almost two decades at the point of writing. It has thus accumulated a lot of debt in different forms that need to be addressed in one form or another to ensure that the project itself remains viable in the long term. This includes topics like:

• Maintenance and refactorings of the Git codebase to reduce technical debt.
• Modernization of parts of the tech stack.
• Improvements to the usability of Git.
• Deprecations and removal of features.

Roadmap

Please see the public product direction for Gitaly.

The current roadmap is this epic board.

Team

Responsibilities | In the product hierarchy

Name	Role
Christian Couder	Staff Backend Engineer, Gitaly
Justin Tobler	Senior Backend Engineer, Gitaly
Karthik Nayak	Senior Backend Engineer, Gitaly
Patrick Steinhardt	Acting Engineering Manager, Git
Toon Claes	Senior Backend Engineer, Gitaly

How to contact the team

We are happy to help when other teams or customers need it. But please keep in mind that we are primarily a development team, not equipped for “field engineering”.

Our engineers can help, preferably asyncchronously, with deep technical investigation based on Git-specific use cases and data and able technical collaboration, in close partnership with Support, CSM and direct users of Git like Gitaly.

Engineering Managers (@pks-gitlab) and Product Managers (@mjwood) are also happy to engage with customers if you need assistance clarifying roadmaps, features and timelines, or to ensure the correct prioritization.

We are not a good fit however if you need:

• Guidance on how Git is used by other teams. While we can provide the expertise on how to integrate it, the actual integration is outside of our reach.
• Advice on workflows and instance configuration or architecture in self-hosted scenarios. (Reference Architectures and Professional Services can help)
• Engagements without clear exit criteria. Please clarify them first, “let’s jump on a call to discuss” is usually in this category.
• Long-term “advise us” scenarios. Please refer to Support and the documentation, or engage Professional Services.

Git Office Hours

The team regularly hosts GitLab-internal Git Office Hours. The event is part of the Gitaly team calender, is announced in due time and typically happens on Wednesday at 2:30pm UTC.

These office hours are mostly used to discuss upstream development in the Git team, but we also encourage other people not part of that team to join in case they want to learn about what is going on in the Git community.

This venue can be used to ask for guidance on specific issues:

• Ask for feedback and guidance on how to integrate Git into the product.
• Discuss interesting edge cases as hit e.g. by our customers.
• Provide feedback on Git features.

Note that this is not intended as a general support forum for how to use Git on a day-to-day basis. A better channel to ask such questions would be #git-help.

Please feel free to chime in and add your topic to the agenda linked above.

Bugs, features, performance

To get Git team work on something, it’s best to create an issue on the GitLab-specific Git issue tracker and add the group::git and workflow::problem validation labels, along with any other appropriate labels. Then, feel free to tag the relevant Product Manager and/or Engineering Manager as listed above.

For information requests and other quick one-offs, feel free to use #g_git on Slack to get attention on the issue.

Urgent issues and outages

If you’re not part of the Support organization, please consider seeking help from them first – Support has better availability and can help in most common cases.

If you still need help, please file an issue here. Post it on #g_git for more immediate visibility and tag EM and PM, and the Support person you’re working with.

Future oncall rotation

NOTE: Gitaly and Git are working on second-tier on-call coverage for well-defined emergencies only. This is not enabled yet; the tentative start date is 2025-01-01.

Please do not page oncall outside of these cases; contact Support instead!

• For production incidents only, SRE or IMOC on-call can page the current Gitaly oncall manually.
• For customer emergencies, Support engineers and managers can page the current Gitaly oncall manually.
• If you’re working on a customer emergency but not part of Support, please contact Support instead.

For these cases, use /pd trigger on Slack, then select the Gitaly rotation. For all other cases please file an issue.

Workflow in upstream Git

Because the Git project is an upstream project, we must use a different workflow.

Planning

The Git project has a different release schedule where a new release is published roughly every three months. The schedule can be seen in the Git project’s calendar. Furthermore, it is expected that most topics will take significantly longer both to develop and to be merged upstream. As a consequence, our usual milestones are not a good mechanism to properly track the target GitLab version in the context of upstream issues.

Instead, we use labels like git-milestone::v2.42 to annotate our target Git version for open issues as well as the actual version something has landed in for completed issues. These milestone labels are applied in addition to our normal milestones.

This means that we assign milestones as a timeframe to schedule the implementation of the work by the Gitaly team members, but this does not correspond to the timeframe when the work will be released by the Git project. Their meaning is reduced to a planning tool such that Git issues continue to show up on usual issue boards and are readily discoverable. Consequentially, our usual way of picking up new work applies to Git issues, as well.

Differences to normal review process

When working with the upstream Git Project, we still use a simple workflow where the developer implements the issue in a topic branch, creates a merge request, and assigns reviewers as usual, where issues and merge requests should be created in our mirror of the Git project. However, because the changes must undergo upstream review, the workflow diverges from our normal workflow

• Changes may optionally undergo internal review.
• After the optional internal review, patches are sent to the Git mailing list.

The meaning of the merge requests thus gets reduced to be purely informational.

Developers are encouraged to skip the optional internal review and instead send their patches to the mailing list directly. In that case, they should add a comment to the merge request that links to the mailing list thread on https://public-inbox.org/git/. The review should then happen on the mailing list directly.

Encouraging developers to send patches to the mailing list directly has multiple benefits:

• Reviewers get exposure to the Git mailing list. This demonstrates to the wider Git community there is a whole team working on Git at GitLab while also building up credibility for the reviewer.
• Topics which may otherwise not get a lot of attention may get more when our own reviews are visible.
• We avoid having to do two sequential reviews, which would otherwise further delay topics.

The optional internal review is specifically with new internal contributors in mind. It should help to lower the bar for entry and reduce the level of discomfort that wider exposure to the Git community may bring with it. In the same spirit, reviewers may post review comments internally first before sending them to the Git mailing list. Ultimately, the goal should be that we mentor these new contributors internally such that they eventually start to post to the Git mailing list directly.

The following is a non-exhaustive list of exceptions where we prefer internal reviews:

• Security issues are implemented in our private security mirror.
• Potentially controversial topics where we need to assess whether a proposed solution addresses our own usecases.

Long-running topics

In some contexts it may be necessary to collaborate on long-running topics when it is infeasible to land changes in a single release. Our usual iterative development approach does not always work well within the Git project. Most importantly, for an open source project the assumption needs to be that contributors may go away in the middle of their endeavour, leaving behind dangling pieces that might have complicated some of our architecture without actually reaping the intended benefits. In contrast to company-led projects, the Git project has no way of ensuring that these would eventually get finished.

For topics that span over multiple releases we are forced to use long-running feature branches until the topic becomes upstreamable. The workflow here is thus different to normal upstream work and happens on a separate topic branch that the developer creates from the current upstream master branch. From here on, the development of the topic happens internally and follows our usual merge request workflow including internal reviews, where each of the merge requests targets the topic branch.

One problem in this context is that the topic branch will eventually start to become outdated when the upstream master branch progresses. While it would be possible to regularly merge from master into the topic branch, the end result would not be in an upstreamable state. On the other hand, rebasing the topic branch on top of master would require other contributors to adapt to the resulting forced update.

Instead, we use a combination of rebases and merges to update the topic branch with upstream’s master branch:

1. The topic branch is fake-merged into the master branch, discarding all changes. The resulting tree is the same tree as the tree of master.
2. All commits of the topic branch are rebased on top of the fake merge.
3. Optionally, the rebased commits are squashed or reorganized so that the result becomes upstreamable.

While complicated, this workflow provides a bunch of benefits:

• We never need to force-update the topic branch.
• The topic branch remains in an upstreamable state.
• The history of the topic branch remains intact, which also means that individual contributions remain intact even if they are squashed into other commits.

This workflow is similar to what Git for Windows uses and can be implemented via its shears.sh script:

## Update origin, pulling in new changes for origin/master
$ git fetch origin
## Switch to the topic branch
$ git switch topic
## Find the current root of the topic branch. This could either be the last fake-merge
$ base=$(git rev-parse ':/Start the merging-rebase')
## Or it could be the merge-base of origin/master and your topic branch
$ base=$(git merge-base origin/master topic)
## Rebase the topic branch onto origin/master
$ ./shears.sh --merging --onto origin/master $base

View page source - Edit this page - please contribute.