Skip to content

Git designed for AI agents.

5.5 KB
Raw Blame

Tips for reading Git source code

Although Git has good documentation, sometimes you just need to read the code to understand how it works. This document collects some tips on how to approach Git's source code.

Audience

This is written for Gitaly developers and GitLab troubleshooters (SRE, support engineer).

Look at the right version

If you want to understand Git's behavior by reading the source, make sure you are reading the right source. Find out the Git version of the system you're investigating and select or check out the appropriate tag in Git.

Use a viewer with code search

Online code search is usually not that great compared with code search in an offline text editor, or on the terminal with git grep.

Look at the tests

If you want to know something that is not clear from the documentation, sometimes the answer is in the tests. These can be found in the t/ subdirectory.

In t/helper you can find C executables that expose some Git internal functions that you normally cannot call directly.

The tests themselves are written in shell script. Instructions for running them are in t/README. However, often you don't have to run a test in order to understand what it are does.

If you're interested in the workings a particular Git command, try searching the t/ directory for it.

Look at the technical documentation

There is a lot of technical documentation in the Git source. If you want to know more about file formats, internal Git API's or network protocols, this is a good place to start.

Code organization

The Git subcommands we use to interact with Git are mostly (all?) found in the builtin/ directory. For example, git log is builtin/log.c.

The .c files at the top level of the Git repository contain code that is shared across sub-commands. For example, config.c contains code related to getting and setting Git configuration values. Contrast this with builtin/config.c, which is the sub-command code for git config.

When doing a code search for an error message you sometimes get false matches in the po/ directory which contains localizations. You may want to ignore those or filter them out of your search.

If you are trying to make sense of what some internal Git function does you can read its definition somewhere in a *.c file in the root. There may also be some extra explanation in the corresponding *.h (header) file; the header files define the API of the corresponding *.c file.

Sub-command source files

Not all sub-commands are written in C

At the top level of the repository, you will find *.sh and *.perl files that implement some of Git's sub-commands. For example, git-bisect.sh.

Main function

If you're used to reading Ruby or Go, the builtin/*.c files could be a little disorienting. This is because the function call graph is ordered with leaf functions at the top, and the main entrypoint will be at the bottom. This allows the Git source code to have fewer (or no) forward declarations of functions.

So if you want to do a top-down walk of a Git sub-command, expect to find the main entry point at the bottom of the corresponding builtin/*.c file. The entry point for e.g. git blame will be called cmd_blame in builtin/blame.c. Recall that hyphens are not allowed in function names, so the entry point for git upload-pack is cmd_upload_pack.

Some functions are not where you expect them. For example, cmd_format_patch is in builtin/log.c. Use code search!

Global state

The way we write Ruby and Go at GitLab, it is common to bundle and hide state in classes (Ruby) or structs (Go). Global state is rare.

Things are different in Git. Builtin commands often use static (i.e. file-scoped) global state. This reduces the number of arguments that have to be passed to functions, just like having state in a Ruby class does.

You usually find the global variables at the top of the file.

C trivia

If you don't use C every day some things about it might be surprising.

Implicit use of "zero means false"

In Ruby, you will never write if some_number because if some_number is a variable containing a number, that if is equivalent to if true. In Go, you are not allowed by the compiler to write if someNumber {.

However, in C, it is OK to write if (some_number): this is equivalent to if (some_number != 0). Whether that is OK is a matter of style, and in Git, you will see that if (some_number) is common.

A variation of this has to do with zero-terminated data structures such as classic C strings, and linked lists. The loop below will visit each character in the string. Note that the test condition of the loop, *s, will be 0 at the end of the string, and the loop will break.

for (s = "some string"; *s; s++)

You will see the same pattern with linked lists, where the test condition is the pointer to the current element.

for (x = my_list; x; x = x-> next)

This becomes even more cryptic if you are dealing with a while loop.

while (x)