git-reference | Online Git Reference at http | Learning library

What happens if I run pull request checker using reference repo and the newest commit has not been cached yet? Will Jenkins fetch missing commits?

Yes. The point of a reference repository is to act as a fast lookaside cache.

In the following, "your Git" refers to your Git software operating on your machine creating your new clone for Jenkins, "their Git" refers to the Git software operating on the machine on which the repository being cloned is hosted, and "reference Git" refers to the repository on the Jenkins machine (it must be on the same machine).

Remember also that a hash ID—whether it's a commit hash ID, or any other internal object hash ID—is meant to be unique to that particular data. That is, the hash ID of every commit in every repository is different from that of every commit in every other repository, since each commit is itself unique. The one exception to this rule about uniqueness of commit hash IDs is if this is literally the same commit: if repository A has commit a123456..., and repository B obtains that commit from repository A, repository B now calls that commit a123456... as well. If repository C obtains that particular commit—from A or B—repository C calls it a123456... too, and so on.

So: your Git calls up their Git. Their Git lists out some branch and tag and other such names. Each name corresponds to one (1) hash ID.

Your Git now picks and chooses over those names: which ones does your Git want? Depending on whether your clone is --single-branch, it will want all of them, or just one of them. It picks out which one(s) it wants, putting those hash IDs into a pool of hash IDs.

Without a reference clone, your Git now sends their Git all of those hash IDs with a "want" message. Their Git adds those hash IDs to a wanted list and looks up those objects. If those objects are commit objects—usually they are, but some of them might be tag objects if you're fetching tags—their Git must now offer the parent commit hash IDs to your Git. (If they're tag objects, their Git must offer the commit hash IDs.) Your Git adds these to its pool of wanted IDs and sends those with "want" messages as well. They then list the parents of those, and your Git "wants" those, and so on.

Using --depth adjusts this process a bit: the two Gits agree that at some depth of this sort of traversal, the two will say "that's enough parent following" and they'll stop the whole offer/want thing. Without --depth, the two Git go on enumerating commits until they've offered, and your Git has "want"ed, every commit.

Their Git now has no more commits to offer, so they begin packaging the to-be-sent commits up, along with all the supporting objects required for those commits. (If you're doing this as a live clone, this is where you see the "counting" "compressing" messages.) They send your Git this package, which your Git opens and unpacks and stores in your clone, and now you have a clone.

Later, your Git can call up their Git again, using git fetch. Their Git will once again list their names and hash IDs. Your Git will check to see which of those commits you already have, and for those commits, tell their Git: No thanks, I already have that one. For commits you don't have, your Git will tell their Git that you want them, and then they'll offer the commit's parents, exactly as before. This conversation continues until your Git and their Git have agreed as to which commits you already have, vs which commits you need. Their Git now counts and compresses and so on—and, because you already have commits and their supporting objects, their Git can avoid sending you anything in those commits. So the package fetched with a git fetch after the first git clone is much smaller and easier to deliver.

When you clone with --reference, the same procedures apply. However, this time, as their Git lists out commit hash IDs, your Git checks two places:

• Do I already have this commit? (For an initial clone the answer is always "no" but for subsequent git fetch operations, it's often "yes").
• Does my reference clone have this commit?

If either one has the commit, your Git says no thanks, I have that one already. If not, your Git says it wants that one, and their Git is now obligated to offer that commit's parent commit(s).

Since commit hash IDs are globally unique, your Git only has any of these commits if it is literally the same commit as the other Git's commit. Whether it's in your own repository, or your reference repository, it is the same commit.

The end result of this cloning or fetching process is the same as the end result of a clone without --reference: your Git now has all the commits that they offered, that your Git needed and therefore took. The difference is that when they offer some commit hash ID, such as a123456..., your Git looks in two places: its own repository database, and the reference repository's database.

There is one other optional difference. When your Git looks in the two databases and finds that the commit they're offering is in the reference database, your Git can either:

• leave it there, on the assumption that it will continue to be there in the future, or
• copy it into its own private database, on the assumption that the reference copy might vanish

The default is to leave it in the reference copy: there's no need to fatten things up with another copy when both sets of database file are on the same host machine. But if you plan to remove or otherwise clean out the reference copy in the future, you may wish to force your git clone --reference operation to make copies at this time. To do that, use the --dissociate option.

Note that this option, like --reference, is only available during the initial clone, not during git fetch. If you:

• make a clone with --reference but not --dissociate;
• then update that clone with git fetch, perhaps over the course of many days or months

some of the internal objects in that clone are still really just stored in the reference clone, but only those that did come from the reference initially, during the initial clone, are still coming from the reference clone. There is no git fetch option to stop using the reference clone here. If you want or need to destroy the reference clone, see below.

Because --dissociate is only available during git clone, to "undo" a reference clone—which then allows you to destroy the original reference—you must now "clone the clone". That is, you will run git clone with the source repository being your clone that uses the reference. Add the --dissociate flag here, so that your new clone of your existing clone-that-depends-on-a-reference-clone makes a full copy. Otherwise your clone-of-existing-clone will just use references to the reference clone.

You most likely want to make this clone-of-a-clone using --mirror, so the "undo reference" operation is actually:

Unlike other version control systems you may be familiar with, commits don't belong to any branch. Instead, a branch is just a label that points to a commit. There's no definitive answer to the question "which branch does a commit belong to" or "which branch was a commit written on". Instead, you can only say what commits are reachable by a branch. And that's just what %S does. It works just like --source.