Git glossary lacunae, part 1

If you work with linguistics, philology, texts or editing, you probably know what a “lacuna” is. If you don’t, then any dictionary will tell you that a lacuna is something that is supposed to be somewhere, but is missing, and it is usually said of texts in which words or whole passages are missing for some reasons.

I already wrote here about how much i hate the source code management system called Git (Git sucks 1, Git sucks 2). Actually, Git itself is probably a good piece of software, but learning it is terribly hard. I’ve been trying to do it for years and i still don’t understand almost anything. Learning Git is hard because every piece of documentation that discusses it is full of cryptic jargon. The solution to this problem is supposed to be in the man page called gitglossary, but it is very incomplete; in philologists’ jargon, it has lacunae.

I compiled a list of Git terms which i found hard to understand and which i could not find in gitglossary. At some point i thought that i would try to understand what these weird words mean myself and send patches with definitions to the maintainers of that file. Unfortunately, i am too busy to do that. The least i can do is to post that list here. If you are a Git expert, consider writing definitions for them and sending them as a patch to Git’s maintainers.

  • add
  • author
  • bisect
  • clone
  • committer
  • diff
  • grep
  • log
  • packed ref
  • remote (as a noun)
  • repo (it means “repository”, of course, but the glossary should mention this abbreviation)
  • reset
  • staging, staging area (a synonym for “index”, if i understand correctly)
  • status
  • treeish
  • working copy (this one seems simple, but it’s not)

These words are defined in the glossary, but the definitions are unclear:

  • parent – I couldn’t understand a word of that definition.
  • reflog – The definition says that this thing “can tell you what the 3rd last revision in _this_ repository was”. It is unclear whether the number 3 hear is just an example or it always refers to the 3rd last revision.
  • checkout – This should be defined very clearly and carefully, because the usage of this term in Git is quite different from its usage in other version control system. The current definition is unclear and circular: a checkout is “the action of updating all or part of the working tree with a tree object”; to understand it one needs to know what a “working tree” is – and it is defined as “the tree of actual checked out files”.

So, i’m sincerely sorry for only bringing up the problem without providing a solution. I hope that it’s better than just doing nothing.

(By the way, i would gladly post it as a bug in Git’s online bug tracking database… except that for some strange reason last time i checked Git developers don’t have one.)


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.