Can we communally deprecate git checkout?
106 comments
·January 9, 2025kazinator
Some things bug me in checkout; it should never have had a -b option so that it does "git branch" things along with checking out. It was probably done that way because early in Git's development, there was a lot of fuss about it having light weight branching, and what looks even more light weight is when you can instantly create a branch and switch to it with one command.
There is a consistency in checkout and reset.
Both checkout and reset can be whole or partial (terms I made up). Partial checkouts and resets specify paths. Whole specify at most a revision.
The checkout operation updates the indexed and working copies of files to be like what is specified in a given revision.
- A whole checkout to another revision, if it succeeds, will update the working files and index to what is in that revision, and move HEAD to it.
- A partial checkout updates the specified files, working and index, to what they look like in the given revision, without moving HEAD.
- A whole reset to to another revision updates just the index to that revision, and moves the current branch and HEAD to it. Working files stay the same.
- A partial reset updates the index entries for the specified files, to the given revision, without moving HEAD or branch. Working files stay the same.
There are obviously more details, due to various options like reset --hard and so on, plus considerations of what happens with a dirty index. But that's the basic paradigm:
(starting with clean tree)
checkout reset
whole moves: HEAD moves: HEAD and branch
updates: working + index updates: index
result: clean result: working diff, nothing staged
partial moves: nothing moves: nothing
updates: working + index updates: index
result: working diff, staged result: working diff, opposite change staged
- the partial operations don't move the HEAD or current branch in both cases; the whole operations do move HEAD or HEAD + branch.
- whole or partial checkout updates working + index.
- whole or partial reset updates index.
cmgriffing
I feel like the value of changing from `git checkout -b` to `git switch -c` is not worth the cognitive overhead of making the change.
kedean
Not to mention the official docs for "switch" still state "THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE."
ghewgill
Yes. This warning in the documentation (and the same warning for "git restore") is doing nothing to help the situation. I've had to put a stake in the ground on this SO answer: https://stackoverflow.com/a/215731/893
epistasis
> [At the time of writing, the git restore command has been marked as "experimental" for at least four years.]
Honestly I have not bothered to even learn switch or restore because of these warnings. If they keep them in after five years, then the commands might be removed in the next version, because clearly there's no champion behind them pushing them forward.
And the few times I have tried to learn what they do, I have not seen any benefit over my current knowledge. So why learn something that may go away and is not trusted even five years and many many versions after deployment?
Izkata
This goes well with my experience from svn where "svn switch" had a high-enough chance to screw up your checkout that everyone I know just had multiple checkouts instead.
BizarreByte
I felt that way about the master to main debacle, but some angry people online won anyway.
joshka
I made that exact thought many years ago and came to the direct opposite conclusion. It was worth the cognitive overhead to make the change and I haven't looked back. Most of the time I'm just hitting aliases (from OMZ's git plugin) https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git e.g.
gsw git switch
gswc git switch -c
gswd git switch $(git_develop_branch)
gswm git switch $(git_main_branch)imoreno
Do people really type these out, instead of just making a bash alias?
camtarn
Used to have bash aliases, but nowadays I work on so many different machine, without my dotfiles present, that aliases seem kinda pointless. I'm a fast typist.
dwaltrip
I would wager that 90% of people using git don’t have bash aliases.
remram
I was always using 'co' for checkout. Made the change to switch ('git s') and revert ('git r') and it has been pretty seemless. I do wish 'git reset' defaulted to --keep.
marssaxman
Wholeheartedly agree with this suggestion.
I don't think I have used the incomprehensible `checkout` command once since I learned that `switch` and `restore` exist, and the previous years-long state of perpetual low-grade irritation I had felt toward git has diminished accordingly.
kazinator
What do you use for navigating in the branch history when doing a git bisect? Can you use switch for that?
remram
I think you're asking for 'git switch -d' (for detached).
In practice you will still need 'git reset' but only with a branch parameter (all 'git reset -- paths' can be replaced with 'git restore'), usually with --keep, --soft, or --mixed.
marssaxman
I'm afraid I have no idea - I've never needed to use `git bisect`.
null
tecoholic
Never have I read Git Pro or have the deep understanding of git’s internals. But I use checkout almost every day, as a shortcut to create a new branch and switch to it, throw away changes that I don’t need and…well, that’s pretty much it.
Now that I have read this article half way, I decided to stop. Because I am learning a few extra things that’s kind of messing up my mental model of what that command does. I think a fair % of git users might be in my boat. Our knowledge, hence our burden is limited.
So community might not be as confused with checkout as the author or those who grok git.
SoftTalker
checkout is one of the few git commands that makes sense to me. I use it a lot, to get back to a known state, after I screw up my working files with other git commands. E.g.
Copy my changed files to a temporary directory.
Delete my working directory.
Checkout the latest version from the repo.
Copy my changed files back.
lukeschlather
The article says that git checkout confuses things that could be better accomplished with one of (git restore, git switch, git reset)
What you're doing sounds like git reset/git switch would be fine. I think I'm in favor of what the author suggests, conflating switch and reset/restore seems bad. It's going to take some effort to fix my habits though.
hmcdona1
Use `git stash` instead of copying files around manually to save yourself some time.
bluedevilzn
Parent comment is the quintessential example from the article that most people who know git didn't learn git properly.
SoftTalker
Yeah git rubbed me the wrong way from the beginning and I never learned it properly. My way makes the most sense to me. Stash? where? How do I get my files back? None of that is intuitive. I understand my way.
mschuster91
Now if git stash would support only stashing one specific file...
Izkata
git stash -- filenamefhars
The one bad point about checkout is that is one of the few git commands that can destroy data irretrievably, even without --force or -f or so. That is unexpected behaviour.
remram
What you want is 'git reset --mixed'
encoderer
What is wrong with me that I dont have any problems with this? Maybe it’s how we name branches? I think I’ve only seen a few cases where I use checkout and it complains about being ambiguous.
cyrnel
It's not hard to change to git switch. I used to have a "co" alias for "checkout" which I removed. I'd say I lost maybe 60 seconds of typing time over the few weeks it took to unlearn the muscle memory.
60 seconds of time investment to be better at mentoring the next generation of technologists is worth it.
JohnMakin
Maybe I am a rube, but people bemoaning "complexity" of git just never strikes home with me. I started using it when I was 14, so maybe that is it (it was still fairly new, but it's all I've ever known) - I still only use a handful of commands.
git checkout, git checkout -b
git pull
git merge (mostly to merge master back into a development branch, or something like that)
git push
git restore (much more rarely)
git reset (even much more rarely)
Barely ever have I had to do anything but these for 99.999% of my workflow, and none of them seem particularly complicated unless you run into merge conflicts, but on every team there seems to be at least one pro "merge conflict" guy. Idk. Checkout is occasionally annoying when it forces you to stash unrelated changes to what you're doing, that's about all I can come up with.
vrosas
I’ve found that people are either die hard rebase fans or die hard merge fans. Neither side can understand the other and I’ve never had it properly explained to me what the difference is or why I should care.
mirawelner
Rebase rewrites history to an extent. What I do (and this is also the advice in Pro Git for what thats worth) is use rebase when I'm working in local because its cleaner, but the moment anything ends up on GitHub, I use merge because I don't want to rewrite history that other people are aware of.
I am fine rewriting my own history on local because I know what I did, but not when its on GitHub because other people don't neccecarily know what I did.
JohnMakin
I think this nails the difference in my workflow against people that tend to say it is difficult. In infrastructure commit history, which is often tied to CI CD processes that reach far outside of a repository and org - commit history is sacred. I need the absolute order of when things got merged in, because it provides a clean timeline to backtrack any issues. maybe I’m doing it wrong but every mature sysyem I’ve worked in basically operates this way. I suspect you run into more merge conflicts but I’m by no means a git expert.
samschooler
Merge = Smooshes two branches together into one. It keeps all the commits from both branches and creates a new "merge commit" to combine them. Doesn't mess with the commit history.
Rebase = Takes all the commits from one branch and sticks them on top of another branch, like stacking them in front. It rewrites the commit history to make everything look like one straight line.
I'm a rebase stan, but that's just my opinion.
fhars
One of the disadvantages of rebase is that it leads to a history where most of the commit have never existed in that exact form an any machine and so have never been built or run. This may interfere negatively with git bisect, which assumes that you can run and test the software at every commit. A squash and rebase workflow doesn't suffer from this problem, but then you end up with huge commits that may make it hard to pinpoint the exact change that causes a new misbehaviour.
Of course, having a merge based workflow doesn't guarantee that people only commit source that runs, so bisect might be broken anyway, and you get a messy history on top of that, unlike the beautiful clean line of a rebase based workflow, that makes it look like the system was developed by people of superhuman mental clarity.
afdbcreid
Wait. If `git bisect` is anyway identifying merge commits only (since those are the only on history), how are you supposed to get advantage of the supposedly superior smaller commits?
nophunphil
I think a lot of the people who use merge do so because that’s what they learned initially.
Anecdotally, a lot of my coworkers who use merge are conceptually trying to stack their commits on top of previous ones. My lukewarm take: most of the time, rebase is actually the intended operation and merge is used as a hammer.
mschuster91
`git merge` is for regular people who are measured by how much they can accomplish in a given timeframe.
`git rebase` is for academics and startups where no one gives a fuck about anything and no one bats an eye if you waste a day or two on a rebase gone wrong.
It's easy to undo a merge and a bit nasty if you already pushed the merge commit. But undoing a rebase? Oh god you're in for a lot of pain.
tomjakubowski
> But undoing a rebase? Oh god you're in for a lot of pain.
It's actually pretty easy. You either make a checkpoint tag before you start the rebase, and reset to it if you notice something went wrong; or, if you forgot to make the checkpoint, check the reflog and find the commit you started from, and reset to that.
Reflog has a flag which adds timestamps to every entry, which I find is helpful for this:
git reflog --date=isoanonymoushn
the old commits are still in your reflog, and if they belong to a branch that isn't only on your machine, you can nag a coworker if you don't know how to use that
alain_gilbert
yeah, totally agree, it's so hard to type `git rebase --abort` (?)
psyclobe
Amen brother haha I have not evolved at all in my git usage and it hasn't really hurt me in any way.
Its not really part of the job to deal with 'insane merge issues', or crazy git tricks and things, only once in a while...
Also, rebasing is so confusing at least in the cmdline sense, I don't see the point.
lukeschlather
This isn't about complexity it's about git putting multiple commands into one and potentially doing stupid things as a result. (Even though I don't think I've ever actually had a problem where I said "git checkout <file>" and git interpreted it as a branch or vice versa. I mean, that happens but I think in every instance no such file/branch has existed so git did nothing.)
In any case, I think checkout does in fact conflate things that should be (at least) two separate commands. That's not "less complex" it's about having more predictable behavior. And arguably it's more complex than the status quo.
bboygravity
have you ever worked with other people on the same project? or Gerrit?
There's really nothing simple, quick or logical about Git when you need to do things like:
copy some files from another repo into yours while preserving file history
copying files within a repo while preserving file history (if you just copy+paste you lose, if you edit the files after moving with git mv, but before comitting the move first, you lose all history)
deleting 1 file from all commits in a repo (almost impossible without using an external non-git tool)
dealing with a rebase that was pushed that shouldn't have happened
I could go on and on with examples of things that should be trivial but aren't.
JohnMakin
> have you ever worked with other people on the same project? or Gerrit? There's really nothing simple, quick or logical about Git when you need to do things like:
Yes, I currently manage my team's merge process and review all code that gets merged into our main repository. I tend to only do trunk-based repositories, work mostly in infrastructure, so I imagine my process is a little different than some traditional "dev" ones, but it's largely uncomplicated on my 5 person team.
> copy some files from another repo into yours while preserving file history
I'm not really sure what this means - I don't often have to do this, can't imagine why I would have to do this. If by "file history" you mean the commits on the file from the other repo? I can't imagine why I'd do that and it sounds like an anti pattern to me, and I avoid doing things like that at all costs, or would just create a git submodule if I really, really had to have that history and file in my repo for whatever reason.
> copying files within a repo while preserving file history (if you just copy+paste you lose, if you edit the files after moving with git mv, but before comitting the move first, you lose all history)
Really never have felt a need for doing this in any repository I've worked in so I guess no, for similar reasons as my above comment
> deleting 1 file from all commits in a repo (almost impossible without using an external non-git tool)
Why would you have to do this with any kind of frequency? If I did, and it was sufficiently complicated, I would put it in automation and write it once and call it a day.
> dealing with a rebase that was pushed that shouldn't have happened
I'm seeing now from other comments what the difference here is, I don't really ever use rebase and never have felt the need to. If I ever worked for a team where I didn't get to decide that, we had tooling that managed that part or wrote it.
> I could go on and on with examples of things that should be trivial but aren't.
I am a little curious, because some of what you wrote sounds a little bizarre to me, but I guess I'm probably in a much different domain.
Izkata
> copying files within a repo while preserving file history (if you just copy+paste you lose, if you edit the files after moving with git mv, but before comitting the move first, you lose all history)
This is much closer a description to svn (and probably other systems), and doesn't describe git at all. Git doesn't store file renames. It reconstructs them from the history based on how similar an "add" and a "delete" were in the same commit. There's even args to change the sensitivity and look for line sources in even broader scopes* - which means git can do one thing others can't, show you where lines came from when two or more files were merged. Others can only show you one of the source files, the one that was explicitly renamed.
* See "-C" in "git help blame", the broadest scope even looks for the source in other commits.
WorkerBee28474
> deleting 1 file from all commits in a repo (almost impossible without using an external non-git tool)
That seems like the exact opposite of the purpose of version control.
Smithalicious
The classic example is accidentally committing a binary file or some other large-as-in-filesize garbage -- simply deleting the file preserves it in history, bloating the size of the repo.
anonymoushn
It ends up being a worthwhile thing to do if someone has checked in a large file that shouldn't be in git or whatever
tverbeure
Somebody accidentally checks in an AWS private key and it gets found out much later.
null
outworlder
I think everyone needs to know the existence of git bisect. That has the side effect of improving individual commits as you'll make sure whatever functionality they implement is atomic.
exceptione
The most important one is
git rebaseJohnMakin
Don't think I've ever used this except by UI's from bitbucket/github etc. when doing a squash commit.
anonymoushn
You never add files, create commits, or rebase?
Often people arrive on a team that has committed a grave sin in the past and all future team members are forced to use workflows involving submodules as penance.
null
cheshire137
Huh. I use checkout multiple times a day every day. It's how I switch branches, including creating new branches. I guess I could use other commands, but why change what's working fine?
joshka
https://github.blog/open-source/git/highlights-from-git-2-23... gives a good overview of the reason for the two new commands.
mac-attack
"The new commands, by contrast, aim to clearly separate the responsibilities of git checkout into two narrower categories: operations which change branches and operations which change files."
Simple, concise breakdown
I'd rephrase and simplify this article a bit.
`git switch` and `git restore` are better alternatives to the `git checkout` command, as they have a lower cognitive overhead and fewer footguns to avoid. Although these commands are marked in the documentation as experimental, they work extremely well in practice. Experimental in this sense means that these may gain or lose behavior over time, not that these commands are unstable for use. As a community, we should use `switch` and `restore` commands rather than `checkout` when documenting / teaching git so that newer users start with a greater ability to reason about how the commands affect their workflow.
For more about the introduction of these commands and the details of the above see https://github.blog/open-source/git/highlights-from-git-2-23...