This in combination with a `git diff` in a split shell works very well for me. For adding changes, I often use `git add -p` - this also gives a nice opportunity to think about a change again. As a bonus, if I did not yet push, I can extend the commit (using --amend) or roll back to it when doing experimental changes. There is also the option to `git stash` some work away.
Currently, I would try to get around the situation posed by simply using fine grained git add to specific files.
But here is a situation I find backwards. If I am doing work, and then I go to commit. I do not want git to do a merge or tell me there is a merge conflict. I mean... I do want to know there is a merge conflict, but I do not want git to try and merge and dump a bunch of merge conflict information in my folders/files.
What I want to do, but git does not seem to have a simple way of doing, is... forget I am trying to commit. Pull down the repo to the latest. Put my files back in. Then let me do a git status, git diff so I can see what my changes are clobbering. What is the correct set of git commands to get it to do that?
I think this is an interesting idea and could be helpful. I started using Magit in Emacs a few months ago, so detangling unrelated changes is a piece of cake now, so I don’t feel like this would actually be a benefit for my workflow. ¯\_(ツ)_/¯
Magit changed how I commit by making it much easier to split up changes. (I'm sure another gui would work well)
Edit:
I think a buffer of lines you navigate is just the right metaphor for working with a bunch of text. It's why line editors are generally considered obsolete.
I'm glad it works for you. For me there's a crucial jump in fluency of using something graphical to select lines that makes willing to be more precise.
I think a buffer of lines you navigate is just the right metaphor for working with a bunch of text. It's why line editors are generally considered obsolete.
Sorry, that comment was pre-caffeine and it probably seemed like I was dissing on the GUI. I meant to suggest git add -p as an option for those who don't want to use Magit or similar, or as an intermediate step between git add . and a GUI diffing tool.
Git add -p is still pretty useful for reviewing individual changes, but slicing finer than that, or editing patchsets directly as text, is definitely a dark art, but one that I'm glad that I have learned through repeated trial and error (e.g. recognizing that the first column must always be a space, plus, or minus). I would probably have added to my prior comment that a specialized diff editor paired with git add -p might be more useful than doing so with a usual text editor.
As a further option, there is also git add -i which is not a great UX and it has its own weird DSL with oddities, but still a slightly "higher level" than git add -p for when people need or want something less fine-grained than git add -p from the command line without installing another git porcelain.
git add -i lets you get the status of files in the working directory, add entire files, revert entire files, or patch individual files, all from a single UI "session". You can do all of the same stuff with appropriate pathspecs to the individual commands such as git add -p just/one/file-i-need.md, but git add -i is an option for those that want an "almost GUI" for that.
I'm not, I've not seen anything else like magit's diff views: they provide a great overview of the entire state (of the working copy or staging area) and allow very fine and nonlinear staging/unstaging.
While technically `git add -p` provides the same capabilities, magit's allowance for jumping around and staging and unstaging (and reverting / killing) as you wish and go is a huge boon, it requires significantly less pre-planning and remembering that `git add -p`'s linear and blinkered (one hunk at a time) workflow
The only thing that I've not found perfect is reverting parts of an existing commit (e.g. re-reading your log you realise that you added debugging crap to a commit): magit will create a staged revert and an unstaged re-add, which is nice to move stuff out of a commit but a bit confusing for straight reverting it. And even that is still miles ahead of everything else I know of.
The only thing magit is lacking is fixing interactive rebases: it beats the pants off of doing interactive rebases manually, but i'd like it to compute "dependencies" between patches so it stops me from moving a patch above its dependency, or at least tells me beforehand (as that usually generates huge conflicts which would be better handled by not moving the patches that way because it's an error, or splitting the patch being moved beforehand).
I prefer magit to other but GUIs, but I think selecting changes is the area it's comparatively weakest (compared to other GUIs, it's far ahead of -p). I'd like a better way to use a mouse, and a way to only commit parts of lines (I know this would involve non-trivial workarounds, but that's why I'm using a git porcelain).
Edit: I also dislike hunks, they never correspond to what I want reliably. Another annoyance is I think magit is quite good at the low level selection in general, but it's hard to get a high level overview because I'm always collapsing and un-collapsing things.
At first I bristled at the notion that the workflow is wrong, but this places the "todo list" front and centre. That's an integration of workflows that makes sense.
That is not how it works, but it's an interesting idea. My worry is that it's a little fragile in the same way that vanilla git is fragile - you can accidentally start working on a new task and mess up your stack.
In reality, git-plan just keeps a directory of draft commit messages for you, and when you run `git plan commit` you can choose one of them to use as the template for your commit message. Essentially, it runs `git commit -t <YOUR_PLAN_FILE>`.
I suppose an ideal tool would be for me to highlight a bunch of lines in the IDE, say "These code changes are part of plan: [ABC/XYZ/Create a new plan...]".
Nice idea, I encounter this problem often during work. I usually end up doing the lazier "git add -a" where a couple of unrelated small fixes get bunched together in a larger commit.
Sometimes I do take the time to organise the changes into multiple commits, but that process is very prone to making mistakes.
The most annoying part is when I accidentally forget to add a crucial one-line chunk belonging to a particular feature I'm working on, so that I have one commit "refactor: ..." that accidentally has an important config change or a one-line change that actually belongs to the feature. So now the feature commit doesn't represent a fully working program. Very annoying.
I'll try this out, see if it works any better. Hope it does!
Shout out to emacs' brilliant git porcelaine magit. It makes doing a bunch of disconnected stuff 'in the zone' and then staging and commiting whichever lines and refs you want totally straightforward and easy.
Fixing a typo as you work on something else is not bad - that's called Boy Scouting[1] and it's totally acceptable to sprinkle small improvements/cleanups in a change.
As for getting distracted and refactoring something else - you're context switching. When you do that, you can also context-switch your repo by stashing your current changes (git stash) while you work on that tangent. Or commit your current changes to their local branch (you're liberally using branches, right? Branches are cheap in Git) and switch to a new branch for refactoring.
If you really want to write your commit first (which is a great idea, because you should know what changes you're planning to make before you start working on them!), then you can create an empty commit when you switch to your new feature branch:
git commit --allow-empty
Write your "plan" as the first commit in that branch. Then do your work, committing frequently, and when you're done and squashing your changes into a single commit for review you now have that first commit available and waiting.
Most issues I see from people getting confused with their changes and using Git is not using enough branches for their work, not being practiced at branch manipulation, and not being disciplined and intentional about their changes. People aren't thinking about "how am I going to release this?" or "how can this be reviewed most efficiently?", and they get carried away with making a lot of changes at once instead of many small changes.
My rule of thumb is that I'm only allowed to take one step off the path/plan, anything else gets put on a todo list to revisit later.
I suggest you take your complaint to the English language office. In Dutch, that organization would be called "padvinders" (lit. pathfinders, i.e. trackers) which shows that the concept itself isn't gendered.
My only issue is that if you fix something small and include that in an unrelated feature or bug fix commit, is if you have to do a "git revert" you are then reverting both items.
That's why you don't squash before merging. If you merge the original commits (and make a separate commit for the minor fix), you can revert the problematic commit without affecting the rest of the feature.
But making a separate commit for the minor fix is onerous once your working copy has accumulated other changes. That's what the OP says -- you have to use "git add -p" and that is onerous.
> Fixing a typo as you work on something else is not bad - that's called Boy Scouting[1] and it's totally acceptable to sprinkle small improvements/cleanups in a change.
Different people have different standards and opinions on what's acceptable. Personally, I'm in the camp of people that would hate to see an unrelated typo fix being included in the same commit as some other change. I strive for semantically meaningful commits, and prefer the people I work with to do the same. It's fine to make such fixes, but they should be in separate commits (though they can be in the same code review request). The pain point the author of the article mentioned is very real (needing to do `git add --patch`).
> Write your "plan" as the first commit in that branch. Then do your work, committing frequently, and when you're done and squashing your changes into a single commit for review you now have that first commit available and waiting.
There are often times when multiple end commits make sense. Squashing/rebasing down to essentials is fine, but that still may be more than just one commit on occasion.
Most people however dont mind them at all and they practically do zero harm. However, forcing people to split it into two commits likely means it wont ever get done.
Because who wants to go through previous commit files to check for typos in other peoples code. People wont, either they fix it as they are noticing them or not at all.
>Most people however dont mind them at all and they practically do zero harm.
They don't do zero harm though. The git blame history gets thrashed. If I see the last change one line 15 of a file is associated with a commit titled `Enable TCP connection reuse`, I'm going to wonder what a change to a line throwing an unrelated exception has to do with that. This means I'll waste time investigating a red herring. If I need to see the blame to find out who to ask about the feature, I also get garbage direction.
The same preference for semantic commits applies to things like optimizations. Don't sneak in keep alive timeout changes in the same commit as `Add email notification support`. If a bug turns up on the email feature, I don't want to waste time potentially looking at the wrong thing.
> However, forcing people to split it into two commits likely means it wont ever get done.
That's not been my experience. They either get corrected at code review time on first release, or someone will make a semantically isolated commit for the fixes and include them in a future code review/pull request.
> Because who wants to go through previous commit files to check for typos in other peoples code. People wont, either they fix it as they are noticing them or not at all.
Not sure what point you're making here. You don't need to go through previous commits to see typos if they're still there in the current commit.
You have to go through them to find the typos again. So you wont.
The harm to history is marginal. It is quite unlikely that you fixed that many typos in all surrounding lines. I have yet to be confused by history like that.
You can fix them as you find them. Just save as a separate commit. No need to go back to find anything.
Typos were just an example. There are other changes that are just as harmful to history that people might otherwise think are safe to squeeze in. Examples include whitespace changes and minor refactors. All of these can really mess with history and make things confusing. Refactors in particular really mess with your head and can even make the code review step confusing if the review wasn't sent with multiple commits.
Keeping semantic isolation of commits has value in its neatness. You may be able to get by without doing so, but you'll be better off if you did.
Yes, you can commit parts of a file at a time. This is easily done by using `git add -p`.
This is a subjective matter, so I don't think your point of view here is wrong or anything, but I do disagree with it. History is something I've consulted many, many times on large code bases. It's helped save precious minutes while triaging situations where an alarm went off and customer was ongoing.
> They don't do zero harm though. The git blame history gets thrashed.
That's exactly it; the keyword here is 'churn'. There was one OS project (I'm sure there's more) that basically said that small (typo, style) pull requests will not be accepted for that very reason.
But that's where gratuitous code review, tooling, and rebasing come in; ideally a feature is complete and reviewed and tidy before it gets merged into master and 'solidified' as part of a project's history. Ideally anyway.
> you're liberally using branches, right? Branches are cheap in Git
Branches may be cheap in Git, but they're expensive in typical modern software eng. process. For every branch, a PR must be opened, code must be reviewed, full test suite must be ran, the testers must ok that the change does not require extending the test suite, and only finally after the whole ordeal we're ok to merge. That's why I prefer my branches big and meaty.
> For every branch, a PR must be opened, code must be reviewed, full test suite must be ran, the testers must ok that the change does not require extending the test suite, and only finally after the whole ordeal we're ok to merge.
Surely this isn't true for local branches on your machine? I hope you're not living under such a dystopia.
Really depends on other changes. Say you change some variable name since whoever was there last forgot to rename something while they did refactoring. Couple days later someone fixes a bug that is related to this variable in some other way. Now you can't simply back port the bug fix commit into earlier release because it relies on a commit that introduces a feature that is not wanted/needed. Obviously fix is simple enough either edit the commit to also contain the variable change or make a tiny "dummy" commit that just contains the fix.
Now whoever is making this decision is cursing you since you could have just made the dummy commit in the first place and prevented this extra work that went into figuring out when the bug fix commit alone wasn't working/compiling.
I didn't know about the empty commit, that's useful.
The approach I try to follow is below. The BLUF is I use a similar but more granular approach and agree with writing the commit before you do the work.
First, I write the commit message capturing the intended design in a file and then try to create a skeleton of API level changes with method names and stubs from my design as my first commit. I use the file as my commit message for this.
Next, as I work I commit freely locally with small commits but I don't push to remote. I do this rather than commit --amend so I can track and revert as needed if needed. I probably could just use --amend.
Last, once I have it working I squash those commits into one commit and push to remote, then merge in changes from master if any and repush, and then start cycle over.
I tend to do this at one level below the issue I am working, so I then still have multiple commits for an issue, one per sub-issue. I will sometimes leave these as is in the PR, or sometimes I will squash these into a single commit as well. Which I do depends on how active the branch I'm targeting with the PR is, how big the commits are, and the extent of the changes.
In addition to empty commits or rebasing work in progress commits, git stash accepts -m/--message and you can write a "proper" commit message when stashing work in progress. Some client apps (I've seen VSCode do it) will even kindly move that message from the stash into their commit message writing box on popping the stash.
I use the git CLI for most things, but if you want to do line-by-line commits, then you're really much better off using a GUI. I recommend Sublime Merge. It starts up almost instantly, so you can leave it closed most of the time and pop it up with `smerge .` in your terminal when you need it.
I cannot overstate how much this post expresses the feeling I have had for a very long time but could not pinpoint and I love the premise for the call to action. People who love Git will no doubt say that the current way is how Git is supposed to work because one must think in an atomic mindset. You declare that you like the whole sum of changes that you made, then commit it with a single commit, OR you have a series of commits and if you realize you made a mistake, change/amend it or do some more questionable things like a hard reset to before the series began, OR just squash the commits when it's time to merge
If I'm wrong about the previous point on how one would carry out the post's vision with current Git, then I would attribute some of that to my opinion that Git CLI isn't very good UX-wise and is why people have made a mountain of GUI tools just for Git
Honestly, I know that Git supports the kind of workflow the post describes, but there is some psychological barrier to making seemingly "permanent" commits because my coding workflow doesn't work that way. It works more like the way the post describes. I like to toy with code, make mistakes, backtrack a ton of times, sometimes restart from zero, or even if there was somehow the "magic pill" solution, it would be awesome if it could somehow automatically associate the files you worked with for a specific feature and know that some subset of the modified files are irrelevant, or at least reduce the number of context switches each time you like a new addition to a giant feature
Our idealized next generation of voice assistants might be able to handle such tasks.
"I need the files I was just playing with added"
"Are the lines 3-10 from main.c related to these?"
"Yes but not lines 8-10"
"Ok, I've hidden the changes that you believe are irrelevant. Try testing again. Does it still work?"
Unfortunately our voice assistants are absolutely nowhere near the kind of fluidity that this kind of voice-based workflow demands and if attempted today, would be extremely frustrating or cause a lot of mistakes. I can't even tell Google or Siri to go backwards on a conversation if I misspoke. I need to restart the entire conversation like I'm speaking to a toddler
My workflow is to edit code, figure out bottom-up how it really works, then look at all the mess, realize I could never get review approval, and stash it.
Then I start over top-down, make the same changes again -- wiser this time -- add in comments which make sense to others, and commit to a new branch. Repeat with another new branch until everything in the stash has been incorporated.
With `git plan` I'd have to skip over the 1st exploration phase. Desirable, but irreducible.
My workflow is the same. The results of the exploration phase are like a prototype - plan to throw it away, keep the learning, then build the final, elegant version.
I do not understand the benefit in the described scenario:
Why not branch for the typo and the code refactoring?
Is it a bad habit to reflect your changes after you coded them?
I see the benefits for a backlog in Git by using git plan, though. I would have used Gitlab Issues for this...
I solve this by committing often without a meaningful message, and rebasing afterwards.
Maybe that could be taken further - have autocommit every few seconds, and then have a `git add --patch`-like workflow, but one that selects time ranges instead of line ranges.
Git's workflow is bad, but this doesn't fix it at all because the real problem in the first paragraph comes when that first paragraph occurs after you've already made some commits, and that can only be solved by either uncommitting a bunch of stuff or committing the next code in the wrong order and then rebasing to rearrange and squash commits.
> to facilitate the feature you're working on you decide to make a small architectural change elsewhere in the codebase
Imagine this happens _after_ you've already made a bunch of commits. So you write some code. You make some commits. And then you run into a wall where you suddenly realize that you really should change something else and do the code in an early commit differently.
Writing your commit messages in advance doesn't solve anything related to git. If you actually already knew all of the commits you'd need to make, you wouldn't ever suddenly decide half-way through to make an architectural change that you hadn't planned to make from the beginning. But you _don't_ already know all of the commits you're going to need to make. That's the problem, and this proposal doesn't address it.
So now you make a new commit for the architecture change, and then you make a dummy commit for the code that uses the new architecture change, and then you git rebase interactive to move the dummy commit after the earlier commit and mark it as a fixup, and you move the architecture change commit before the whole thing, and then you pray that nothing is broken in the process.
fugitive.vim makes it very fast to do laser-focused partial commits, you just have to remember to do it 2-3 times a day. It's really very good. I think Magit in the Emacs universe does more or less the same.
Git-gui (bundled with Git) doesn't look that nice, but is also pretty fast for making partial commits.
My impression after reading this is that the author needs a better git client. magit, SourceTree, or Fork (my personal favorite at the moment) let you stage individual lines and chunks, which is life changing.
If you find a typo or something you want to be in another commit, stage that line and commit it and carry on. Use rebase and cherry pick later to move commits around as you want.
> git add --patch can help here, but it's still tedious work.
This is pretty much the operative line of the post. Rather than invert my whole development flow, I just use a UI like Magit which makes patch commits trivial.
Context-switching is hard. Having the discipline to prioritise effectively is hard, using git branches effectively is hard, and building tools to magically make it easier is...hard.
Git-plan doesn't solve this problem outright, but I hope it moves in the right direction.
I do think that once you have draft commit messages in your workspace, it is possible to build new tools that consume them to help you context switch. For example, a tool could automatically stage hunks for you, based on the draft commit message you wrote.
There are some great thoughts and criticisms here and I'll be taking them all onboard for the next couple of versions of the tool. If anyone wants to contribute, PRs are welcome and I can help out as needed.
If you have a good code review system, like Gerrit or Rietveld, you can do what I do.
Every single commit and upload is immediately followed by `git checkout -B master origin/master`.
Use WIP tags for things you intend to keep working on and download the patch and upload new patch sets as you continue. Using the code review tool as a substitute for branches and continuously doing work off of a clean master has changed my life.
This is a bit of a sensational title. Developers are empowered by Git to use a workflow that works for them. This is exactly what the person has done, they've made a workflow that works for them.
One is free to commit any time they like, it's not "Git's commit workflow", Git itself does not have an opinion on when you commit, just how.
Bad habits are not encouraged by Git, people get lazy, or complacent, and learn bad habits.
There are GUIs that allow you to stage and commit hunks of code intuitively, but GUIs are often shunned by people who spend a majority of their time in the CLI - however I am sure Vim and the like have some kind of tool for doing something similar.
I disagree. In any tool some things are easier and others are harder. The easier ones will be done more often. We can parcel out blame between users and tools, or we can be more productive and work to improve both.
Git add -p reminds me of ed. And sure, you can technically write anything in ed. Still, there's a reason we improved on it.
My first thought was 'oh no, not yet another git command!" but I get where the author is coming from.
However, the dangerous part is including a refactor in an unrelated change. Good luck backing that out if you need to.
Personally, when I'm in this situation I just park what was supposed to be doing and then do the refactor separately.
I agree it's a problem - but I don't think there is an easy solution nor that the article presents a solution.
The problem was just that I was distracted or forced to solve a different problem than I had planned. Making a plan doesn't change that. If anything, it leads to ending up with a planned commit message that is still unrelated to the changes (which seems worse than having no commit message at all)?
104 comments
[ 0.28 ms ] story [ 166 ms ] threadYou could create a commit and —amend work into it if that is the route you’d like to take.
But here is a situation I find backwards. If I am doing work, and then I go to commit. I do not want git to do a merge or tell me there is a merge conflict. I mean... I do want to know there is a merge conflict, but I do not want git to try and merge and dump a bunch of merge conflict information in my folders/files.
What I want to do, but git does not seem to have a simple way of doing, is... forget I am trying to commit. Pull down the repo to the latest. Put my files back in. Then let me do a git status, git diff so I can see what my changes are clobbering. What is the correct set of git commands to get it to do that?
Edit: I think a buffer of lines you navigate is just the right metaphor for working with a bunch of text. It's why line editors are generally considered obsolete.
I think a buffer of lines you navigate is just the right metaphor for working with a bunch of text. It's why line editors are generally considered obsolete.
Git add -p is still pretty useful for reviewing individual changes, but slicing finer than that, or editing patchsets directly as text, is definitely a dark art, but one that I'm glad that I have learned through repeated trial and error (e.g. recognizing that the first column must always be a space, plus, or minus). I would probably have added to my prior comment that a specialized diff editor paired with git add -p might be more useful than doing so with a usual text editor.
git add -i lets you get the status of files in the working directory, add entire files, revert entire files, or patch individual files, all from a single UI "session". You can do all of the same stuff with appropriate pathspecs to the individual commands such as git add -p just/one/file-i-need.md, but git add -i is an option for those that want an "almost GUI" for that.
I'm not, I've not seen anything else like magit's diff views: they provide a great overview of the entire state (of the working copy or staging area) and allow very fine and nonlinear staging/unstaging.
While technically `git add -p` provides the same capabilities, magit's allowance for jumping around and staging and unstaging (and reverting / killing) as you wish and go is a huge boon, it requires significantly less pre-planning and remembering that `git add -p`'s linear and blinkered (one hunk at a time) workflow
The only thing that I've not found perfect is reverting parts of an existing commit (e.g. re-reading your log you realise that you added debugging crap to a commit): magit will create a staged revert and an unstaged re-add, which is nice to move stuff out of a commit but a bit confusing for straight reverting it. And even that is still miles ahead of everything else I know of.
The only thing magit is lacking is fixing interactive rebases: it beats the pants off of doing interactive rebases manually, but i'd like it to compute "dependencies" between patches so it stops me from moving a patch above its dependency, or at least tells me beforehand (as that usually generates huge conflicts which would be better handled by not moving the patches that way because it's an error, or splitting the patch being moved beforehand).
I wish it allowed me to stage a hunk, too. But I make do with staging all lines from that hunk. It is not a lot more effort.
Edit: I also dislike hunks, they never correspond to what I want reliably. Another annoyance is I think magit is quite good at the low level selection in general, but it's hard to get a high level overview because I'm always collapsing and un-collapsing things.
At first I bristled at the notion that the workflow is wrong, but this places the "todo list" front and centre. That's an integration of workflows that makes sense.
The utility offered though doesn't address the fact that now non-related changes are still bundled together.
We've just managed to write the git commit message earlier?....
So you're working on "git plan --commit-message='important feature'" or whatever the syntax would be.
Then you encounter a place where some refactoring would be really helpful, so you do
"git plan --commit-message='refactor: ...'"
Any changes made during this plan won't show up in the original git plan.
I'm not sure if this is how it works, but that's how I understood it.
In reality, git-plan just keeps a directory of draft commit messages for you, and when you run `git plan commit` you can choose one of them to use as the template for your commit message. Essentially, it runs `git commit -t <YOUR_PLAN_FILE>`.
(I'm the author)
I suppose an ideal tool would be for me to highlight a bunch of lines in the IDE, say "These code changes are part of plan: [ABC/XYZ/Create a new plan...]".
It's even earlier in development than git-plan, but the `commit -m "some message"` command works.
Sometimes I do take the time to organise the changes into multiple commits, but that process is very prone to making mistakes.
The most annoying part is when I accidentally forget to add a crucial one-line chunk belonging to a particular feature I'm working on, so that I have one commit "refactor: ..." that accidentally has an important config change or a one-line change that actually belongs to the feature. So now the feature commit doesn't represent a fully working program. Very annoying.
I'll try this out, see if it works any better. Hope it does!
As for getting distracted and refactoring something else - you're context switching. When you do that, you can also context-switch your repo by stashing your current changes (git stash) while you work on that tangent. Or commit your current changes to their local branch (you're liberally using branches, right? Branches are cheap in Git) and switch to a new branch for refactoring.
If you really want to write your commit first (which is a great idea, because you should know what changes you're planning to make before you start working on them!), then you can create an empty commit when you switch to your new feature branch:
Write your "plan" as the first commit in that branch. Then do your work, committing frequently, and when you're done and squashing your changes into a single commit for review you now have that first commit available and waiting.Most issues I see from people getting confused with their changes and using Git is not using enough branches for their work, not being practiced at branch manipulation, and not being disciplined and intentional about their changes. People aren't thinking about "how am I going to release this?" or "how can this be reviewed most efficiently?", and they get carried away with making a lot of changes at once instead of many small changes.
My rule of thumb is that I'm only allowed to take one step off the path/plan, anything else gets put on a todo list to revisit later.
Plan the work, then work the plan.
[1] https://www.informit.com/articles/article.aspx?p=1235624&seq...
How about calling it "camp grounding"?
https://biratkirat.medium.com/step-8-the-boy-scout-rule-robe...
And the word 'scouting' already means "moving ahead of a group to gather information", which makes sense in the software engineering context too.
[1] https://en.wikipedia.org/wiki/Scouting
Different people have different standards and opinions on what's acceptable. Personally, I'm in the camp of people that would hate to see an unrelated typo fix being included in the same commit as some other change. I strive for semantically meaningful commits, and prefer the people I work with to do the same. It's fine to make such fixes, but they should be in separate commits (though they can be in the same code review request). The pain point the author of the article mentioned is very real (needing to do `git add --patch`).
> Write your "plan" as the first commit in that branch. Then do your work, committing frequently, and when you're done and squashing your changes into a single commit for review you now have that first commit available and waiting.
There are often times when multiple end commits make sense. Squashing/rebasing down to essentials is fine, but that still may be more than just one commit on occasion.
Because who wants to go through previous commit files to check for typos in other peoples code. People wont, either they fix it as they are noticing them or not at all.
They don't do zero harm though. The git blame history gets thrashed. If I see the last change one line 15 of a file is associated with a commit titled `Enable TCP connection reuse`, I'm going to wonder what a change to a line throwing an unrelated exception has to do with that. This means I'll waste time investigating a red herring. If I need to see the blame to find out who to ask about the feature, I also get garbage direction.
The same preference for semantic commits applies to things like optimizations. Don't sneak in keep alive timeout changes in the same commit as `Add email notification support`. If a bug turns up on the email feature, I don't want to waste time potentially looking at the wrong thing.
> However, forcing people to split it into two commits likely means it wont ever get done.
That's not been my experience. They either get corrected at code review time on first release, or someone will make a semantically isolated commit for the fixes and include them in a future code review/pull request.
> Because who wants to go through previous commit files to check for typos in other peoples code. People wont, either they fix it as they are noticing them or not at all.
Not sure what point you're making here. You don't need to go through previous commits to see typos if they're still there in the current commit.
The harm to history is marginal. It is quite unlikely that you fixed that many typos in all surrounding lines. I have yet to be confused by history like that.
Typos were just an example. There are other changes that are just as harmful to history that people might otherwise think are safe to squeeze in. Examples include whitespace changes and minor refactors. All of these can really mess with history and make things confusing. Refactors in particular really mess with your head and can even make the code review step confusing if the review wasn't sent with multiple commits.
Keeping semantic isolation of commits has value in its neatness. You may be able to get by without doing so, but you'll be better off if you did.
History is not that epically useful that we should avoid cleanups.
This is a subjective matter, so I don't think your point of view here is wrong or anything, but I do disagree with it. History is something I've consulted many, many times on large code bases. It's helped save precious minutes while triaging situations where an alarm went off and customer was ongoing.
That's exactly it; the keyword here is 'churn'. There was one OS project (I'm sure there's more) that basically said that small (typo, style) pull requests will not be accepted for that very reason.
But that's where gratuitous code review, tooling, and rebasing come in; ideally a feature is complete and reviewed and tidy before it gets merged into master and 'solidified' as part of a project's history. Ideally anyway.
Branches may be cheap in Git, but they're expensive in typical modern software eng. process. For every branch, a PR must be opened, code must be reviewed, full test suite must be ran, the testers must ok that the change does not require extending the test suite, and only finally after the whole ordeal we're ok to merge. That's why I prefer my branches big and meaty.
Surely this isn't true for local branches on your machine? I hope you're not living under such a dystopia.
Code reviews length takes exponentially longer and misses way more when branches are "big and meaty"
Now whoever is making this decision is cursing you since you could have just made the dummy commit in the first place and prevented this extra work that went into figuring out when the bug fix commit alone wasn't working/compiling.
The approach I try to follow is below. The BLUF is I use a similar but more granular approach and agree with writing the commit before you do the work.
First, I write the commit message capturing the intended design in a file and then try to create a skeleton of API level changes with method names and stubs from my design as my first commit. I use the file as my commit message for this.
Next, as I work I commit freely locally with small commits but I don't push to remote. I do this rather than commit --amend so I can track and revert as needed if needed. I probably could just use --amend.
Last, once I have it working I squash those commits into one commit and push to remote, then merge in changes from master if any and repush, and then start cycle over.
I tend to do this at one level below the issue I am working, so I then still have multiple commits for an issue, one per sub-issue. I will sometimes leave these as is in the PR, or sometimes I will squash these into a single commit as well. Which I do depends on how active the branch I'm targeting with the PR is, how big the commits are, and the extent of the changes.
Which absolutely should be a new branch and probably a different ticket.
If I'm wrong about the previous point on how one would carry out the post's vision with current Git, then I would attribute some of that to my opinion that Git CLI isn't very good UX-wise and is why people have made a mountain of GUI tools just for Git
Honestly, I know that Git supports the kind of workflow the post describes, but there is some psychological barrier to making seemingly "permanent" commits because my coding workflow doesn't work that way. It works more like the way the post describes. I like to toy with code, make mistakes, backtrack a ton of times, sometimes restart from zero, or even if there was somehow the "magic pill" solution, it would be awesome if it could somehow automatically associate the files you worked with for a specific feature and know that some subset of the modified files are irrelevant, or at least reduce the number of context switches each time you like a new addition to a giant feature
Our idealized next generation of voice assistants might be able to handle such tasks.
"I need the files I was just playing with added"
"Are the lines 3-10 from main.c related to these?"
"Yes but not lines 8-10"
"Ok, I've hidden the changes that you believe are irrelevant. Try testing again. Does it still work?"
Unfortunately our voice assistants are absolutely nowhere near the kind of fluidity that this kind of voice-based workflow demands and if attempted today, would be extremely frustrating or cause a lot of mistakes. I can't even tell Google or Siri to go backwards on a conversation if I misspoke. I need to restart the entire conversation like I'm speaking to a toddler
My workflow is to edit code, figure out bottom-up how it really works, then look at all the mess, realize I could never get review approval, and stash it. Then I start over top-down, make the same changes again -- wiser this time -- add in comments which make sense to others, and commit to a new branch. Repeat with another new branch until everything in the stash has been incorporated.
With `git plan` I'd have to skip over the 1st exploration phase. Desirable, but irreducible.
I see the benefits for a backlog in Git by using git plan, though. I would have used Gitlab Issues for this...
Maybe that could be taken further - have autocommit every few seconds, and then have a `git add --patch`-like workflow, but one that selects time ranges instead of line ranges.
> to facilitate the feature you're working on you decide to make a small architectural change elsewhere in the codebase
Imagine this happens _after_ you've already made a bunch of commits. So you write some code. You make some commits. And then you run into a wall where you suddenly realize that you really should change something else and do the code in an early commit differently.
Writing your commit messages in advance doesn't solve anything related to git. If you actually already knew all of the commits you'd need to make, you wouldn't ever suddenly decide half-way through to make an architectural change that you hadn't planned to make from the beginning. But you _don't_ already know all of the commits you're going to need to make. That's the problem, and this proposal doesn't address it.
So now you make a new commit for the architecture change, and then you make a dummy commit for the code that uses the new architecture change, and then you git rebase interactive to move the dummy commit after the earlier commit and mark it as a fixup, and you move the architecture change commit before the whole thing, and then you pray that nothing is broken in the process.
Git-gui (bundled with Git) doesn't look that nice, but is also pretty fast for making partial commits.
In fact, I think git outright encourages you to make lots of small diffs.
Feel free to squash groups of your commits before you merge in.
Makes git bisect debugging a hell of a lot easier as well.
If you find a typo or something you want to be in another commit, stage that line and commit it and carry on. Use rebase and cherry pick later to move commits around as you want.
This is pretty much the operative line of the post. Rather than invert my whole development flow, I just use a UI like Magit which makes patch commits trivial.
(and 'git push --force' to 'git yolo', then later to 'gpf', but don't tell anyone)
Context-switching is hard. Having the discipline to prioritise effectively is hard, using git branches effectively is hard, and building tools to magically make it easier is...hard.
Git-plan doesn't solve this problem outright, but I hope it moves in the right direction.
I do think that once you have draft commit messages in your workspace, it is possible to build new tools that consume them to help you context switch. For example, a tool could automatically stage hunks for you, based on the draft commit message you wrote.
There are some great thoughts and criticisms here and I'll be taking them all onboard for the next couple of versions of the tool. If anyone wants to contribute, PRs are welcome and I can help out as needed.
Every single commit and upload is immediately followed by `git checkout -B master origin/master`.
Use WIP tags for things you intend to keep working on and download the patch and upload new patch sets as you continue. Using the code review tool as a substitute for branches and continuously doing work off of a clean master has changed my life.
One is free to commit any time they like, it's not "Git's commit workflow", Git itself does not have an opinion on when you commit, just how.
Bad habits are not encouraged by Git, people get lazy, or complacent, and learn bad habits.
There are GUIs that allow you to stage and commit hunks of code intuitively, but GUIs are often shunned by people who spend a majority of their time in the CLI - however I am sure Vim and the like have some kind of tool for doing something similar.
Git add -p reminds me of ed. And sure, you can technically write anything in ed. Still, there's a reason we improved on it.
Later with "rebase -i" I move all such commits at the start of the branch, and in case deploy them with an earlier merge.
However, the dangerous part is including a refactor in an unrelated change. Good luck backing that out if you need to. Personally, when I'm in this situation I just park what was supposed to be doing and then do the refactor separately.
It helps reviewers and is more transparent.
The problem was just that I was distracted or forced to solve a different problem than I had planned. Making a plan doesn't change that. If anything, it leads to ending up with a planned commit message that is still unrelated to the changes (which seems worse than having no commit message at all)?