Welcome to the 90th edition of Git Rev News, a digest of all things Git. For our goals, the archives, the way we work, and how to contribute or to subscribe, see the Git Rev News page on git.github.io.
This edition covers what happened during the month of July 2022.
[PATCH 0/2] git(1) doc + “git help”: split-out user & git format docs
Last October, Ævar Arnfjörð Bjarmason sent a patch series containing only 2 patches. The first one created a new “User-facing file formats” section in the main Git manual page by splitting it off from the existing “Guides” section. The reason for this was that it was a stretch to have manual pages like “gitignore(5)” in a section called “Guides” which otherwise contained pages like “gitcore-tutorial(7)”.
The second patch in the series created a new “Git file and wire formats” section in the main Git manual page. Contrary to the section created by the first patch, this one was only for internal file and wire formats, that users were not supposed to touch, like “gitformat-bundle(5)”.
The goal was to make the existing technical documentation, which was
in “Documentation/technical/” and available only in the HTML format,
more accessible and discoverable by moving it over into the new man
page sections and adding the corresponding --user-formats and
--git-formats option to the git help command.
The documentation had to be converted when moved over as the man page format was different from the previous technical documentation format, but the second patch only converted “bundle-format.txt” to a new “gitformat-bundle(5)” man page. The plan was to convert and move over more of them later.
Last December Ævar sent a version 2 of his patch series which now contained 5 patches instead of 2 and converted and moved over more documentation to the new man page sections.
The cover letter of this patch series contained the following
examples of what the new git help options would show:
$ git help --user-formats
The user-facing file formats are:
gitattributes Defining attributes per path
githooks Hooks used by Git
gitignore Specifies intentionally untracked files to ignore
gitmailmap Map author/committer names and/or E-Mail addresses
gitmodules Defining submodule properties
gitrepository-layout Git Repository Layout
$ git help --git-formats
Git's internal file and network formats are:
gitformat-bitmap The bitmap file format
gitformat-bundle The bundle file format
gitformat-chunk Chunk-based file formats
gitformat-commit-graph Git commit graph format
gitformat-index Git index format
gitformat-pack-protocol How packs are transferred over-the-wire
gitformat-protocol-capabilities Protocol v0 and v1 capabilities
gitformat-protocol-common Things common to various protocols
gitformat-protocol-v2 Git Wire Protocol, Version 2
gitformat-signature Git cryptographic signature formats
As well as for the first patch series, there was no comment on this patch series except for one from Eric Sunshine about a possible typo. Ævar replied to Eric agreeing to fix some wordings.
A version 3 of his patch series appeared only last July on the mailing list. Containing 7 patches, it converted and moved over even more documentation to the new man page sections.
Ævar soon spotted that gcc’s -fanalyzer option complained about
some code in his patch series though. The issue was that the git
help code, which was matching a user requested topic with a man
page, assumed that the name of man page files started with “git” and
then dropped this prefix. This was justified as all Git man page
filenames have always started with “git”, but the -fanalyzer
detected that things could go wrong if that was not the case.
So a few days later Ævar sent
a version 4
of his patch series with only minor changes. One of them was fixing
the -fanalyzer complaint by adding a new patch at the beginning of
the series which would abort the current command using the BUG()
macro in case the man page name didn’t start with “git”.
Junio Hamano, the Git maintainer, replied to Ævar suggesting a slightly different fix for the complaint. Junio also thought that “githooks(5)” didn’t really belong into a category named “user-formats”, as a hook can be written in any language, so there is no “format” for users to follow. Instead, he would have liked a better name for a category that could contain both “gitignore” and “githook” related pages.
Junio also suggested not distinguishing between <guide> and
<doc> categories in the git help documentation, as at some point
we would have enough <doc> documents that most probably everything
not related to a specific command would become <doc>.
About the “user-formats” category name, Ævar replied that he couldn’t find a better word than “format”. He thought about “layout” as there is “gitrepository-layout(5)”, but found it odd.
He also proposed using <name> instead of <doc> or <guide> in
the git help documentation. Junio replied that he preferred <doc>
to <name> though.
Ævar and Junio also discussed interactions of the patch series with patches that were worked on by others at the same time.
A few days later Ævar then sent a version 5 of his patch series which mainly renamed “user formats” and “developer formats” to “user interfaces” and “developer interfaces”.
These changes allowed the new “user interfaces” section to also contain the “gitcli”, “gitrevisions” as well as “githook” man pages, while the “developer interfaces” had pages called “protocol-*” instead of only “format-*”:
$ ./git help --user-interfaces
User-facing repository, command and file interfaces:
attributes Defining attributes per path
cli Git command-line interface and conventions
hooks Hooks used by Git
ignore Specifies intentionally untracked files to ignore
mailmap Map author/committer names and/or E-Mail addresses
modules Defining submodule properties
repository-layout Git Repository Layout
revisions Specifying revisions and ranges for Git
$ ./git help --developer-interfaces
File formats, protocols and other developer interfaces:
format-bundle The bundle file format
format-chunk Chunk-based file formats
format-commit-graph Git commit graph format
format-index Git index format
format-multi-pack-index The multi-pack-index file format
format-pack Git pack format
format-pack-cruft The cruft pack file format
format-signature Git cryptographic signature formats
protocol-capabilities Protocol v0 and v1 capabilities
protocol-common Things common to various protocols
protocol-http Git HTTP-based protocols
protocol-pack How packs are transferred over-the-wire
protocol-v2 Git Wire Protocol, Version 2
Along with other small fixes in the git help documentation, the
new version also didn’t distinguish between <guide> and <doc>
categories anymore.
The only comment on this version was from Eric who found a trivial typo in a commit message.
Anyway a few days later Ævar sent a version 6 of his patch series fixing the trivial typo.
Junio commented that the first patch in this series, which had been
added in version 4 of the patch series to fix the -fanalyzer
complaint, wasn’t really needed. What wasn’t actually needed was the
BUG() macro aborting everything in case the name of the man page
didn’t start with “git”, as it could be an unnecessary roadblock if
we ever wanted to add such man pages.
After some further discussion, Ævar sent a version 7 of his patch series.
This series mostly removed the BUG() macro that had been added
previously, but in the first patch still refactored the code
dropping the “git” prefix when a user requested topic needs to be
matched with a man page.
Junio commented about this first patch that he wasn’t sure the commit message properly described what the code was doing in case the man page name started with something like “git-git”.
He then spotted an issue with how some changes were split into different patches, and suggested that a man page should be split into different pages for different topics, while two other man pages about similar topics should be merged into one. He also mentioned some “leftoverbits” that could be done later.
Ævar sent a version 8 of his patch series taking account Junio’s suggestions, except for one documentation page, which he decided to be converted later if needed, so he just removed the changes converting it from the patch series.
Junio reviewed the series again and liked what it was doing. He discussed further changes a bit with Ævar, but they agreed that they could be done later in another patch series.
Since then, version 8 of the patch series has been merged into the master branch, so we should have a significantly improved documentation and help system in the next Git feature release (v2.38.0) that should be out in the first weeks of October.
Who are you and what do you do?
I’m a Software Engineer at Google on a team that works on Git. My prior experience is comprised solely of different flavours of proprietary web apps, so I’m constantly grateful for the opportunity to work on the polar opposite of that :).
The only interesting thing I do outside of work is rock climbing. Sometimes, I wish I spent as much time rock climbing as I do working, which probably means that I should figure out how to do both simultaneously.
What would you name your most important contribution to Git?
Hm, I’ve only been contributing for a short while, so it’s hard for me
to call any of them important per se. The most user-visible one is
safe.bareRepository, but I don’t think many users will use it in its
current form. If I had more time, I’d expand it into a safer default for
everyone.
What are you doing on the Git project these days, and why?
Most of my work has been focused on getting submodules to work with branches as well as general submodule cleanup work. I get a kick out of searching “git submodule bad”, nodding my head at every single complaint and dreaming about the day I get accurate search results for “git submodule good”.
If you could get a team of expert developers to work full time on something in Git for a full year, what would it be?
I’d probably find a different way to structure the test suite so that we could share far less state between tests, or maybe come up with a way to visualize the setup for each test case. It would be nice to be able to read just a single test case to understand what’s happening.
If I had 5 teams of experts and 10 years I’d lib-ify all of Git’s internals and have the Git CLI call the Git library in the same way everyone else calls libgit2.
If you could remove something from Git without worrying about backwards compatibility, what would it be?
I’d remove nearly all of the CLI flags and replace them with more consistent, mnemonic flags. It’s fun to be able to throw Git CLI trivia at friends, but at some point, maybe it would be better for them to be able to remember it themselves.
What is your favorite Git-related tool/library, outside of Git itself?
I owe almost everything I know about Git to Magit (the Emacs plugin). When I was much much newer to Git, it was a safer, friendlier, more discoverable entry point than the Git CLI. These days, it’s still an essential part of my toolbox since it vastly reduces the number of keystrokes (I’m a really bad typist) and it gives an amazing interface for modifying and applying diffs (I still have not touched “git add -p” and at this point, I think it’s too late to start).
Honourable mention goes to git-branchless. It does so many amazing things that I’ve grown to rely on, like anonymous branches, obsolescence tracking, and history manipulation.
Do you happen to have any memorable experience w.r.t. contributing to the Git project? If yes, could you share it with us?
Jeff King, one of the most prolific contributors, took a break from the Git project last year. I was probably one of the first people to realise when he came back from the break because his first email on the mailing list was a bug report comment on a bug that I created :’).
Could you describe your Git development toolbox?
For reading email, I’ve configured an email folder for the mailing list, which gets pulled down by offlineimap + notmuch. I read email using notmuch-emacs, which claims to be a frontend to notmuch, but is actually also a full-fledged MUA (just like how Emacs claims to be a text editor, but is actually an OS).
For reviewing patches, I apply the patches to a dedicated worktree using b4. “b4 shazam” is as close to painless as I can imagine.
For sending patches, I wrote a bunch of scripts around “git format-patch” and “git send-email” and organised my branches so that I could keep track of each version I sent out. Then one day I tried GitGitGadget, realised that it does nearly all of those things for me for free, and those scripts have remained virtually unused since :). I will probably never use them again once GGG learns how to base topics on topics.
What is your advice for people who want to start Git development? Where and how should they start?
The best place to start is to get acquainted with the mailing list and the community. Reading the mailing list and sending a low-stakes patch (like a doc fix or usage string fix) are pretty good ways to do this. Folks on the mailing list tend to communicate in a distinctive style – it’s often direct, and silence can have a different meaning from what you’re used to. I’m guessing that for most people, learning how to communicate effectively on the mailing list is harder than the actual technical aspects of Git development.
I’d also recommend that newcomers fight the urge to make their v1 patches absolutely perfect. The community is pretty accommodating to new contributors, so once you’re convinced that the codebase is better off with your change than without, it’s fine to send it out! Far more often than not, it will lead to a positive interaction.
If there’s one tip you would like to share with other Git developers, what would it be?
Assume good intent from the people you interact with. I think the mailing list can be intimidating at times (especially to newcomers), but if you assume good intent, then everyone suddenly seems friendlier and feedback becomes easier to receive. And of course, remember to pay it forward by acting with good intent.
Various
Git tools and sites
This edition of Git Rev News was curated by Christian Couder <christian.couder@gmail.com>, Jakub Narębski <jnareb@gmail.com>, Markus Jansen <mja@jansen-preisler.de> and Kaartic Sivaraam <kaartic.sivaraam@gmail.com> with help from Glen Choo, Carlo Marcelo Arenas Belón and Johannes Schindelin.