Git Rev News: Edition 112 (June 30th, 2024)

Welcome to the 112th 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 months of May and June 2024.

Discussions

Reviews

  • [RFC PATCH] docs: document upcoming breaking changes

    Patrick Steinhardt sent an RFC patch to the mailing list that created a new “UpcomingBreakingChanges.md” document. The goal of the document was to inform users and developers of deprecations and breaking changes, and to encourage discussion of the direction of the project regarding these topics in advance.

    Patrick noted that the changes listed in the document, along with links to mailing list threads where they had been discussed, were a work in progress with controversial and missing items, and that he didn’t want to push for a Git 3.0 release with the listed changes soon.

    The idea for that new document had been discussed previously in a thread about a patch series from Patrick that introduced subcommands like get, set, etc, in git config. In that thread, after Patrick asked if we wanted to introduce a document to keep track of upcoming removals for a potential Git 3.0 release, Junio Hamano, the Git maintainer, replied to Patrick that in a few of his “What’s cooking” emails before the Git 2.44.0 release, he had written:

    It may not be a bad idea to reflect on what technical debt and UI warts we have accumulated so far to see if we have enough of them to start planning for a breaking Git 3.0 release (or, of course, keep incrementally improve the system, which is much more preferable – continuity and stability is good).

    So Junio was happy that “somebody has bit it ;-)” and suggested a number of topics that could be added to the document Patrick wanted to create. This started a discussion about the possibility of deprecating some features, such as the restore, switch, submodules and worktrees subcommands.

    In the RFC patch to add the document, Patrick mentioned some of the topics suggested by Junio, but not others that seemed controversial in the previous discussion.

    Johannes Schindelin, alias Dscho, replied to Patrick’s RFC patch saying he loved it. Dscho also gave his opinion about the topics, and suggested to deprecate or remove additional rarely used features.

    Junio replied to Patrick’s patch suggesting to add features that we don’t want to drop and why, and to mention that we deprecate but, for backward compatibility, rarely remove old ways to do things. Patrick agreed to Junio’s suggestion and proposed a “superseded” section for the features we don’t want to drop.

    Dragan Simic, who had participated in the discussions of the preceding git config thread, repeated that he didn’t want to see any of git restore, git switch or git checkout deprecated, which Patrick agreed shouldn’t be done.

    Phillip Wood, replying to Patrick’s patch, asked if the document should track the progress of some unfinished work, like the config based hooks implementation. Patrick said he was planning on creating a separate document for long running projects, projects already discussed, and also small or micro projects, with the additional intent to help newcomers looking for something to work on.

    Justin Tobler also replied to Patrick’s patch suggesting adding the removal of double dot and triple dot syntax (“..” and “…”) from git diff to the document. This was discussed by Junio and Patrick but, as it would need a lot more work, Patrick decided to not add it to the document for now.

    Patrick then sent a version 2 of his patch adding a section about features “that are not to be deprecated” and proposing some further deprecations, while withdrawing the $GITDIR/hooks directory deprecation proposal.

    Karthik Nayak replied to the patch version 2, listing a number of commands not mentioned in the document that do similar things, which might indicate that some of them could be deprecated too. Patrick, Junio and Dragan discussed these commands, but decided that only git pickaxe, which is an alias for git blame, could be removed for now.

    So Patrick sent a version 3 of his patch, which only added the removal of git pickaxe.

    Junio replied to this version 3 with a lot of comments to discuss how each item was justified and how we could improve on justifying items in general. Patrick then agreed on ways to improve the document.

    Patrick sent a version 4 where the single patch had been broken down into 4 patches. In the process a lot of the proposed deprecations from the previous version were removed and the document name was changed from “UpcomingBreakingChanges.md” to “BreakingChanges.md” as some changes listed in the “Superseded features that will not be deprecated” section should not be considered upcoming.

    The goal was to introduce the document in a skeletal form in the first patch and then add only one item to each of the three sections in the following patches. This way each of the last 3 patches should be an example of how other items should later be added to the document.

    Junio, Patrick and Todd Zullinger then discussed relatively small improvements to the form and content of the document.

    Patrick sent a version 5 of the patch series where the main change was that the document was converted to AsciiDoc instead of Markdown and renamed from “BreakingChanges.md” to “BreakingChanges.txt” for format compatibility with most other documents in the codebase.

    Junio, Phillip Wood and Patrick discussed other small improvements, which Patrick integrated into version 6 of the patch series.

    Junio then suggested a few more small improvements, which Patrick finally integrated into version 7 of the patch series, which was later merged into the ‘master’ branch.

Other News

Light reading

 

  • Programming in Unison by Daroc Alden on LWN.net (free subscriber link). Unison is an MIT-licensed programming language, where programs are stored in an append-only, content-addressed database (though still displayed to the user for editing as text, using the editor of their choice)… just like information about project versions is stored in Git.

Git tools and sites

  • setuptools-scm is a tool that extracts Python package versions from git or hg metadata instead of declaring them as the version argument or in an SCM managed file. Additionally, it provides setuptools with a list of files that are managed by the SCM (i.e. it automatically adds all of the SCM-managed files to the sdist). Unwanted files must be excluded via MANIFEST.in. The preferred way to configure setuptools-scm is via pyproject.toml.
    The latest version and the stable version documentation are available on Read the Docs.
  • piku, which was inspired by dokku, allows you to do git push deployments to your own servers, no matter how small they are. An open source PaaS (Platform as a Service) alternative to services such as Heroku. Written in Python.
  • gitchangelog is a tool that creates a changelog from git log history. Written in Python; no longer actively developed (version 3.0.4 is from 2018).
  • git-open-remote is a shell script by masukomi to open the web page(s) for the repo’s remote(s). With this script you can simply cd into a git repo and type git open-remote. Requires open or xdg-open (aliased or linked to open) to open the web browser, and charm gum to implement the selection UI when the Git repo has more than one remote.
  • Git EOL Conversion Diagram for checkout as Gist providing an SVG version and an editable version on Mindmup, by Martin Leduc (@DecimalTurn).

Releases

Credits

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 Štěpán Němec, Bruno Brito, David Aguilar, Brandon Pugh and Dragan Simic.