gitlink

Gitlink is a term used in Git to describe a special type of tree entry that represents a submodule reference within a superproject. A gitlink is stored in the index as a tree entry with mode 160000 and an object id that corresponds to a specific commit in the submodule’s repository. In essence, the superproject does not store the submodule’s files; it stores a pointer to a particular commit in the separate submodule repository.

How it works: When a submodule is added with git submodule add, Git creates a subdirectory for the submodule and records a gitlink in the superproject’s tree. The superproject also maintains a .gitmodules file with metadata such as the submodule’s path and URL. The submodule itself has its own repository, history, and branches. The gitlink in the superproject records the exact commit of the submodule that should be checked out when the superproject is checked out.

Updating a submodule involves changing the submodule’s commit to point to a newer state, then committing the new gitlink in the superproject to record that updated reference. Cloning a repository with submodules typically requires an additional step to initialize and fetch submodule contents, often via git submodule update --init --recursive or a recursive clone.

Notes: A gitlink is not a regular file blob; it is a special tree entry that points to a submodule’s commit. Submodules introduce independent histories and can complicate workflows, leading many teams to explore alternatives such as subtree merges or worktrees.