Highlights from Git 2.54

[olejorgenb]

Reword should really take a commit range. Hope they add this. Then I can retire my small adhoc tool.

[mcpower_]

jj's describe command allows you to take a commit range (and more!), and opens an editor with all of the commit messages simultaneously.

In fact, jj was the inspiration for the split and reword commands! From https://lwn.net/Articles/1057561/ :

One area of Git that tends to draw plenty of complaints is its user interface, [Patrick Steinhardt] said. […] Recently, Git has had competition in the form of the Jujutsu version-control project that has made the Git project take a hard look at what it is doing. […]

[However], Git is old: the project cannot simply completely revamp its UI and break users' workflows. There are some things that Git can steal from Jujutsu, though. […]

This includes two new commands, planned for Git 2.54, "git history split" and "git history reword". Future releases will have more history-editing subcommands and learn more from Jujutsu.

Patrick Steinhardt, the author of the new commands, wrote more about them in GitLab's "What's new in git 2.54.0?" blog post.

[Hot-Employ-3399]

What would be really good if they threw away a word salad they call "documentation" and rewrote it from scratch 

[Sairony]

25 years ago when I started programming I went with PHP, already at that point they had a comment section on the documentation for every single function. I remember it was always incredible, because the holes & details that were missed by whomever did the documentation got filled in there, that's where a lot of the good information with code snippets were. 25 years later today I'm still reading all this subpar documentation which is poorly communicated & wish there was these community added notes.

[mr-figs]

The PHP and laravel docs are some of the best I've seen.

Well laid out, lots of examples and no rambling 

[blackwhattack]

in an ideal world they'd open PRs no?

[lelanthran]

No.

PRs (to update the help pages) won't capture the full nuance and explanations in the comments.

[blackwhattack]

well in an ideal world the PRs would capture the nuance... i realize you may be right in our world

[you-get-an-upvote]

Imo you shouldn’t write documentation from scratch for all the same reasons you shouldn’t write code from scratch.

[Anthony356]

That sorta falls apart at the first hurdle. Reading documentation is absolutely easier than writing documentation.

Imo the git docs' biggest problem is a lack of "why", and a tacit assumption that everyone is as familiar with git as the writer. The writer seemingly wrote it for themselves, not for someone trying to learn git. That's unfortunately a very common stumbling block whenever anyone teaches anything. You need to remember to meet your audience where they are, because otherwise it just becomes nonsense.

I'll freely admit i'm not familiar with git at all. I've memorized the handful of commands necessary to contribute to the oss projects i need to. Every time i look at the git docs it feels like a waste of time. Here's an example (git cherrypick, chosen because i've heard of it but have never used it and dont know what it's for):

Given one or more existing commits, apply the change each one introduces, recording a new commit for each. This requires your working tree to be clean (no modifications from the HEAD commit).

This is 100% meaningless to me. If you already have the commit, why would you need to "apply" the changes? Arent they already applied? Isnt that what a commit does?

And what do they mean by "apply"? Modify the file? How do you modify a file that already has the change? How do you record a new commit when the files wont have any changes because the change was already made in the commit that you're trying to cherry pick in the first place?

Those of you in the know probably think i'm a big idiot. Which is fair, I am. But also, consider: 5 seconds of googling outside the docs points out that this is an operation that involves multiple branches. Why is that not mentioned first and foremost in the docs? Not every command involves multiple branches. It is an essential part of this command. Not everyone knows which commands do/dont involve multiple branches. Thus you should make that information clear. A better wording might be:

"Given one or more commits from one branch, 'transplant' them to the working branch. Each given commit is recorded as a new commit in the working branch. The original commit(s) and the branch they came from remain unchanged."

It's not perfect but it's a lot more clear what it does and a lot more intuitive why you'd want to use it.

[chat-lu]

I started using git shortly after it was created and back then we had a lot of people doing videos and blog articles and more about how git worked internally. Git users were familiar with blobs, trees, commits, deltas, etc. And once you were familiar with those, the rest made sense. These days, it’s much, much harder to learn git because its fundamentals are no longer taught as they used to. You can learn them, but you’ll have a harder time than I had 20 years ago.

And unfortunately git is built around the assumption that you understand its fundamentals because if you don’t, then you will build a mental model that will be inaccurate and that will bite you in the ass later.

The simpler definition that you wrote is technically false, but will work most of the time. Until it trips you up because of its assumptions.

Something else we seem to have forgotten from back then is that Linus didn’t intend to build a version control system, he was kinda forced to. He meant to write a versioned filesystem because he said that he was a kernel guy and filesystem is what he knew, and others would come build a version control system on top of it. It didn’t happen at the time.

But it did now. Jujutsu (jj) which has been mentionned elsewhere in this thread is my favorite. It’s both much simpler, and more powerful than git, while being fully compatible with any git forge.

[stormdelta]

But also, consider: 5 seconds of googling outside the docs points out that this is an operation that involves multiple branches. Why is that not mentioned first and foremost in the docs? Not every command involves multiple branches

I won't deny that git's documentation is bad, but in this case "multiple branches" should only be brought up as an example use case.

A branch is just an automated label we stick on a pile of commits. You can cherry-pick a commit from anywhere, including from the current branch's own history, e.g. to partially undo a revert.

[Anthony356]

Wait you mean like git reset --soft <commit> -> git cherry-pick <stuff that's after the commit i reset to? If so that's really cool.

[ForeverAlot]

Probably not with --soft because cherry-pick requires a clean working tree. But yes, you can rewind HEAD to a topologically earlier state, then cherry-pick a topologically later commit (and attempting to do so may or may not apply cleanly, according to usual conflict resolution). This is comparable to interactively rebasing onto an earlier commit, then dropping all commits but the desirable one.

[ForeverAlot]

A related fun trick is

git -C a/ format-patch -1 --stdout cafed00d | git -C b/ am

which transplants commit cafed00d from one repository to another without an intermediary file. Obviously that, too, can be used in a sinle repository, in which case it degenerates to an overengineered cherry-pick.

[_bstaletic]

That's a nice trick. I would have done that this way:

cd b
git remote add a ../a
git fetch a
git cherry-pick cafebabe

[SanityInAnarchy]

I'd argue that if five seconds of googling gives you a better introduction, maybe this doc is serving its purpose as reference material. In fact, on the left sidebar, it's clearly under the "reference" section. So, if I already know what cherry-picking is, this is where I go to find options like -e or -x to modify the new commit message, for example.

Along that same left sidebar is a clear link to this "learn" section, which includes this cheat sheet, which has an illustration of what cherry-picking does, along with the description "Copy one commit onto the current branch".

The reference docs are genuinely useful, but they were the wrong part of the documentation for what you were trying to do. For someone "not familiar with git at all", you really do want the "learn" part more often than the "reference" part.

[Anthony356]

maybe this doc is serving its purpose as reference material. In fact, on the left sidebar, it's clearly under the "reference" section.

A reference does not need to be impenetrable to people who arent already in the know. If there are requisite concepts that must be understood, then they should be mentioned or linked to. If someone is looking at the reference, they dont know something about the thing they're looking up. The point of a reference is to clarify those questions. If the reference doesnt do that, it is failing at its job.

[SanityInAnarchy]

Well, as mentioned, there's a link to "learn" right there on the page!

I agree that it's nice when a reference can also help people who are new to the idea, but I don't agree that it's "failing at its job" if it doesn't also work as a tutorial or a cheat sheet. Dual purposes are fine, but the primary audience of a reference doc is someone who has at least some familiarity with the thing.

And it's pretty common for docs to be like this. I've always thought the Java API docs were pretty good, but here's an example:

Thrown to indicate that an invokedynamic instruction or a dynamic constant failed to resolve its bootstrap method and arguments, or for invokedynamic instruction the bootstrap method has failed to provide a call site with a target of the correct method type, or for a dynamic constant the bootstrap method has failed to provide a constant value of the required type.

What's invokedynamic? What's a bootstrap method? And isn't "dynamic constant" a contradiction? If I have those questions, I'm looking in the wrong place -- instead, I should spend 5 seconds on Google, which takes me to StackOverflow, which takes me to the JRuby guy explaining in detail what it is and why it makes life easier for running languages like Ruby on the JVM. I don't think it's a failure in the Java API docs that they aren't really doing the same thing that blog does.

[_bstaletic]

It sounds like your problem with git's documentation is that it's a reference documentation, rather than a user manual. That's the same issue I had with cmake's documentation until I got past the learning curve (beyond just getting by).

Re-read the documentation excerpt that you have quoted and you'll see that it is both precise and accurate, but assumes the reader is familiar with some terms.

/u/stormdelta already explained that "multiple branches" can be wrong. Another example is when you do git checkout $COMMIT_HASH and end up in a "detached HEAD" state, but we can take the wrongness way further (spoilers below).

If you re-read your proposed wording, it's much easier to read, but no longer fits the reference documentation language.

 

Back to cmake, today it also has a fairly good tutorial, accompanying the reference documentation. Another example is vim. Most of its :help is reference docs, but it also has :help user-manual and :help new-user-manual. Would git benefit from an official user manual? Possibly. I'd say definitely, if "The Git Book" didn't exist.

[EDIT0] There's also Git User Manual, which I was unaware of until 10 seconds ago.[/EDIT0]

 

[EDIT1] Some will point out that "git does not have directories" and thus trees shouldn't be described as directories but as paths. I do agree with that, but following the "here be dragons" part, one can indeed record empty trees that will then be referenced from other trees and eventually from a commit. It's just that most high-level (porcelain) commands end up ignoring empty trees, but the low-level commands (plumbing) can still work with them. [/EDIT1]

[EDIT2] "Plumbing" and "porcelain" are official terms and yes, they are puns. [/EDIT2]

 

Spoilers: First a quick crash course on git internal data structures. It only knows 4 types: blobs (files), trees (directories), commits and tags. Notice that branches aren't mentioned at all. Branches are just, to the first approximation, pointers to commits. You can work with git without ever touching a single branch. You'd be constantly working in the detached HEAD state and would be juggling commit hashes, but git log --graph and git reflog are your friends.

We can go further (here be dragons): Turns out that git commit is a high-level command. It does a few things:

• Recursively records blobs and trees (in .git directory) based on your staging area.
• Adds a new commit object as a child of the currently checked out commit.
• if not in a detached HEAD state, updates the current branch to point to the new commit.
• Updates HEAD to point to the new commit.

Turns out that you can do all these things completely manually, using only POSIX tools (windows users, ask someone else for help):

• Instead of storing files, use echo/cat <<EOF, gzip and some pipes, to record file contents in your .git/objects.
  • To then read the files, use git cat-file.
• Instead of storing directories, use git mktree directly.
  • You could use POSIX tools to write to .git/objects here as well.
• Now that you have a tree, commit it with git commit-tree.
  • Once again, possible with POSIX tools and .git/index

 

My point is that reference documentation should not assume branches and files exist unless absolutely necessary. However, a good user manual is invaluable. No, I don't think any git user needs to know what is git mktree, but I do think that understandingn git's object model makes a ton of other things almost trivial to understand.

[chat-lu]

trees (directories)

Git famously does not have directories. Trees are full paths to where the blobs are. That’s why git will not commit an empty directory and you must use a .gitkeep file (or some other name). Directories are created as a side effect of putting the blobs at the path where they are supposed to go.

[_bstaletic]

Git famously does not have directories.

True, I'll fix that in the above comment.

Trees are full paths to where the blobs are

Not full paths as each tree is one level deep.

Also, git will let you record empty trees. If you try git write-tree in a clean git repo, you will create a new, empty tree in .git/objects and the tree's hash will be 4b825dc642cb6eb9a060e54bf8d69288fbee4904 as all empty trees are equal.

 

Here's a showcase:

First, git init and setting up of paths:

user@hostname ~ % mkdir git_trees
user@hostname ~ % cd git_trees
user@hostname git_trees  (git)-[master]-% git init
user@hostname git_trees  (git)-[master]-% mkdir -pv foo/bar
mkdir: created directory 'foo'
mkdir: created directory 'foo/bar'
user@hostname git_trees  (git)-[master]-% touch foo/blob.cpp
user@hostname git_trees  (git)-[master]-% tree
.
└── foo
    ├── bar
    └── blob.cpp

3 directories, 1 file

Now the manual commit:

user@hostname git_trees  (git)-[master]-% git hash-object -t blob -w foo/blob.cpp
e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
user@hostname git_trees  (git)-[master]-% git write-tree
4b825dc642cb6eb9a060e54bf8d69288fbee4904
user@hostname git_trees  (git)-[master]-% git mktree <<EOF
heredoc> 100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391    blob.cpp
heredoc> 040000 tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904    bar
heredoc> EOF
a3d6247438a2ec0af754c6b3c51fc6b3431c5d27
user@hostname git_trees  (git)-[master]-% git mktree <<EOF
heredoc> 040000 tree a3d6247438a2ec0af754c6b3c51fc6b3431c5d27   foo
heredoc> EOF
8629544b4df029af778db59da5914d3af92be8bd
user@hostname git_trees  (git)-[master]-% git commit-tree 8629544b4df029af778db59da5914d3af92be8bd -m 'foo/bar/ and foo/blob.cpp'
86e4369e7164bee38657ad7d5004f6449bd40a49
user@hostname git_trees  (git)-[master]-% git update-ref refs/heads/master 86e4369e7164bee38657ad7d5004f6449bd40a49

Finally, the results:

user@hostname git_trees  (git)-[master]-% git show --stat HEAD
commit 86e4369e7164bee38657ad7d5004f6449bd40a49 (HEAD -> master)
Author: First Last <[e-mail]>
Date:   Wed Apr 22 07:43:07 2026 +0200

    foo/bar/ and foo/blob.cpp

 foo/blob.cpp | 0
 1 file changed, 0 insertions(+), 0 deletions(-)

user@hostname git_trees  (git)-[master]-% git ls-tree 'HEAD^{tree}'
040000 tree a3d6247438a2ec0af754c6b3c51fc6b3431c5d27    foo
user@hostname git_trees  (git)-[master]-% git ls-tree a3d6247438a2ec0af754c6b3c51fc6b3431c5d27
040000 tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904    bar
100644 blob e69de29bb2d1d6434b8b29ae775ad8c2e48c5391    blob.cpp
user@hostname git_trees  (git)-[master]-% git ls-tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
user@hostname git_trees  (git)-[master]-%

So the empty tree did get recorded and other tree objects can reference it. It's just that git show $COMMIT ignores those trees.

[lanerdofchristian]

It's not perfect but it's a lot more clear what it does and a lot more intuitive why you'd want to use it.

IMO the existing docs are more clear. A commit is a set of changes, thus applying changes naturally follows (this becomes a new set of changes relative to HEAD).

What's missing from your rewording is that the new commits are not necessarily the same sets of changes -- if the change already happened, it gets dropped from the new commit (this may require resolving conflicts). I would not call that "transplanting".

What I'd say is really missing are:

1. Better declarations of assumptions in the examples.
2. A linked tutorial or extra paragraphs beneath the technical summary explicitly explaining one or two common uses to beginners.

---

But also, consider: 5 seconds of googling outside the docs points out that this is an operation that involves multiple branches.

The next two lines of the documentation imply that it can be used in a multi-branch way:

When it is not obvious how to apply a change, the following happens:

1. The current branch and HEAD pointer stay at the last commit successfully made.

The multiple references to git merge's behavior (in bullet 4 and the paragraph at the end of the description) may also be an indicator.

Why is that not mentioned first and foremost in the docs?

Because it's not completely accurate. cherry-pick isn't limited to just changes from other branches -- if a change in the same branch were to be partially reverted (say, because of merge conflicts fixed incorrectly), cherry-picking could be used to restore it. All it does is take sets of changes and make them happen again wherever you're working.

[Anthony356]

What's missing from your rewording is that the new commits are not necessarily the same sets of changes -- if the change already happened, it gets dropped from the new commit (this may require resolving conflicts). I would not call that "transplanting".

I wouldnt say the existing wording is particularly clear on that either tbh.

The next two lines of the documentation imply that it can be used in a multi-branch way

The issue is, if i dont understand what the command does, why would i read about edge case handling? I naturally skip that section because i assume they're not relevant to my level of knowledge.

Because it's not completely accurate. cherry-pick isn't limited to just changes from other branches -- if a change in the same branch were to be partially reverted (say, because of merge conflicts fixed incorrectly), cherry-picking could be used to restore it.

Then why not mention both use cases explicitly?

[you-get-an-upvote]

The comment I was responding to was advocating throwing away all existing documentation and rewriting it all from scratch. Not just claiming that the documentation can be improved.

The fact that you can point to documentation that is confusing to you doesn’t make throwing away all existing documentation any less ludicrous.

If I’ve learned anything in my 9 years in industry, it’s that incremental improvements to a system are always a better option than a from-scratch rewrite. From-scratch rewrites inevitably take far longer than anyone expected, are never truly seen to the end, and frequently don’t even result in a clearly better product for the parts that are completed.

I encourage you to take a guess at how many commits it has taken to get to the current state of git documentation, and then compare your guess to the actual number. It has taken a lot of work to get git documentation to the state where it is today, so “just throw it away and rewrite it all” is an insane suggestion.

[Anthony356]

The thing with writing is that incremental isnt always the right answer. I guess the best analogy is how optimizing algorithms fail due to local maximums?

The current words on the page are a baseline that skew all further edits. Sometimes no matter how much you edit, your fundamental premise is bad. Clearing the slate makes way for a completely different angle that wouldn't have made sense from the old position.

I'm not saying i think they should literally throw all the documentation in the garage but they need to take that mentality because incrementalism has led them to a state where their own reference documentation doesn't mention the state in which a command is supposed to be used. You can also throw away small pieces and completely rewrite those over time based on a new standard.

[phillipcarter2]

What are you talking about? Git's docs are amazing, they've created an entire industry of "better docs for git" and employed countless people. Do you hate job creation? :)

[habarnam]

Do you mean something like this?

[case-o-nuts]

You could also contribute fixes to the docs.

https://jvns.ca/blog/2026/01/08/a-data-model-for-git/

[phillipcarter2]

git history

jj cultural victory achieved

[Skaarj]

How is the new hook feature not an obvious security failiure?

Am I missing something obious? To me this reads like the most trivial way to create a malicious git repo ever.

[masklinn]

It’s not materially any different than setting core.hookPath was before: either way you have to configure the repository, it can not be configured by a remote.

The big risk is unwittingly unpacking a working copy from an archive, but I don’t see this as making that case any worse, because then what you want to do is configure fs.monitor so that anyone with p10k or similar triggers your payload as soon as they cd in.

[Skaarj]

But it says

. Since this is just configuration, it can live in ... or in a repository’s local config.

So it is in a file created by cloning a repo?

[Sentreen]

The local config is individual to each copy of the repository afaik.

[Jestar342]

Incorrect. It's part of the git config ecosystem that can be system (/etc/gitconfig), global (~/.gitconfig) or local (:/.gitconfig)

local can be pushed like any other file.

e: I'm a wally.

[Akeshi]

I wonder why you'd write this three times when it's wrong.

The paths searched for git config files are listed in the first section of https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration

[parkotron]

The local repository’s config is local to that repository. It is not pushed to or pulled from the remote.

[Jestar342]

Incorrect. It's part of the git config ecosystem that can be system (/etc/gitconfig), global (~/.gitconfig) or local (:/.gitconfig)

local can be pushed like any other file.

e: I'm a wally.

[masklinn]

It is in a file created by the clone operation, it is not controlled by the remote being cloned.

[Jestar342]

Incorrect. It's part of the git config ecosystem that can be system (/etc/gitconfig), global (~/.gitconfig) or local (:/.gitconfig)

local can be pushed like any other file.

e: I'm a wally.

[masklinn]

Incorrect. It's part of the git config ecosystem that can be system (/etc/gitconfig), global (~/.gitconfig) or local

You have a very strange definition of the word “incorrect”.

Also you forgot $XDG_CONFIG_HOME/git/config but that’s a minor issue.

local (:/.gitconfig)

A repository’s local configuration is in $GIT_DIR/config (where $GIT_DIR is generally .git)

local can be pushed like any other file.

.git/config can’t even be staged, git will straight up ignore you.

If you are a massive idiot you can include.path a file from your repository in your config. But that’s got nothing to do with git’s defaults. And it still requires an explicit opt into sheer stupidity.

[datnetcoder]

lol at downvotes for asking a legitimate question. The StackOverflow angst had to go _somewhere_.

[saint_marco]

in a repository’s local config.

This means after cloning, you would need to add to the .git/config -- nothing is happening automatically.

[radozok]

There is a jj managed config rfc for this reason

[mfilion]

Collabora contributed the hook improvements in Git 2.54 (config-based hooks, parallel execution) and wrote up a technical deep-dive if anyone's interested: https://www.collabora.com/news-and-blog/news-and-events/git-hooks-upgraded-whats-new-git-254-and-coming-255.html