Hacker News Reader

I agree with that. Both the ergonomics and the quality of implementation of git submodules are currently atrocious. Special mention if you try to mix them with worktrees. I think there is a small possibility that they will become usable in 10 years, and an even smaller in 5.

But for now: don't use git submodule. I did not believed that once, because they kinda look nice on paper. Don't do the same mistake. At least wait 5 years before trying them. And test them appart during at least 6 months, actively each day, before taking a dependency and actually making your project use them.

What makes you think that submodules will improve? I've used them for the last ten years or so (when I was forced to) and haven't seen any advances in UX.

I agree. In principle the promise of submodules is a very good, logical and clear one – it is totally understandable why anybody would like to use them, because it would just make sense in a lot of cases.

However the way they are implemented is just so horrible, I side with you here: Don't use them for anything serious. It is not worth it. Invest the time into writing a bash script that does the copying for you, use private package managers for shared dependecies or whatever, but don't use submodules – this way you will at least know what bites you when it does.

Exactly: they're so appealing the first time you find out about the feature. "Oh, i can just go `git submodule add <repo> <path>` and it includes another repo! Very cool!", and then two months later you're staring at the 427th time submodules have caused weird issues when changing branches or whatever, and you just want to hurl your computer into the sea. A hacked-together bash script like you suggested is a far better solution.

> and you never examine the history of the submodule anyway, how often do you look at the history of your dependencies?

All the time. Software is made of bugs, each of your dependencies has bugs, it's on you to diagnose them and, quite often, fix them. Git history is invaluable in those scenarios.

Generally, I'm in favor of pasting the dependencies in your repo. It protects you against things like the leftpad incident and also keeps things nicely in one place, you don't have to go to multiple places to fetch the full source of your program. It also ensures that you have an accurate view of how complex your creation actually is.

But history of dependencies is also useful. At work, we have one giant, heavily patched third-party dependency and a lot of small ones. The big one lives in a submodule. The small ones are pasted in the repo. There is no end to the bugs in them, history is then very useful. And before you say anything, they aren't some random npm packages not vetted by anyone. They're widely-regarded foundational open source projects.

Package managers on the other hand discourage e.g. modifying the dependencies to debug problems in the application. There are more and less correct ways to do that, but generally it's a hoop to jump. With submodules or vendoring - no problem. They also create an illusion of your project being simpler than it really is and are prone to leftpad. And downloading things at build-time is an anti-pattern.

My perspective on software is this: all software has bugs, now the question is: how do we deal with it? How will we debug it? Sadly, there is a lot of "let's assume this works perfectly all the time and do something else" mindset going around as well. Like... How do you debug a malfunctioning GC in your managed language of choice? Will you be able to debug the dependency you've just pulled into your project? Is this language feature a compile-time nicety that will make the interactive debugging later miserable?

If you control the dependency and if you're the primary user, just move it into your repository by merging with unrelated histories.

If you're not controlling the dependency, you can still merge the dependency with an unrelated history on every version upgrade. This will still likely consume less time than fighting submodules every day.

Disagree. Package managers cause more headache than anything. I have used submodules for almost all of my projects (aside from e.g. Node.js projects). Not once have had issues with them.

I don't know why people raise such a stink about them.

> I have used submodules for almost all of my projects (aside from e.g. Node.js projects). Not once have had issues with them.

Do you do things with git beside the trivial operations (add/commit/etc.)? Like rebasing/merging and such across commits that introduce or remove submodules? Do you never encounter friction when e.g. removing submodules? Do you never run into the errors people complain about?

I absolutely despise submodules, but under many use cases you don't add or remove that often. We definitely run into errors people complain about. In fact there are errors that the average user (that doesn't really care about SVC) pretty much can't fix... or with much difficulty. I don't know that I'd still say it's a dealbreaker, but that's definitely very bad. Very much does break some of the spirit of git and what makes it "nice".

We've been using them, and our system is still very usable (obviously this is a ridiculous thing to brag about, but worth pointing out).

I'm wondering if there's a better way to handle shared code between two repos, where the users of either don't have access to the other parent? You might be able to use subtrees? Email source code and just create n separate commits for n projects, with a standardized commit message?

I'd be happy to do something different, but I never had some idea that I could sell in a meeting, and didn't really have the energy or clout to fight this.

My preferred solution has been git-subrepo: https://github.com/ingydotnet/git-subrepo

Basically is what (I think) submodules should have been. Creates a vendored copy with metadata about what commit it came from. Normal operations like clone, commit (even touching multiple main/subrepo files which subtree struggles with) are unaffected (normal files from git's point of view).

Pull, push, branching all work as expected on main project (most devs don't even need to know there's a subrepo). If you want to pull/push vendored changes from subrepo, there's a new command, but that's it.

This just described every feature that submodules gives you out of the box. I'm curious what value this adds, if any...

I can't answer in general, but I do see one possible misunderstanding: "vendored" means the code is copied into the parent repo.

If a submodule's original source goes offline, a new clone of the parent repo won't be able to retrieve it, since it just stores a reference to where to clone from. If subrepo really vendors the code, that'll never be a problem since a full copy is committed directly to the parent repo.

This is what mirroring or forking is for...

As Izkata mentions, the superproject has _all_ the files for a given commit without any need for users to have access other repos, additional submodule init commands, etc.

Basically, after a subrepo clone, you've copied the file tree for the subrepo and can make commits on it in the superproject to your heart's content (branching, etc). This is basically a fork/mirror, but adds a single metadata file to track the last upstream commit you pushed/pulled from to allow reconciling later. So with git subrepo, you make commits in the superproject first and can choose (at some later point, if at all) to merge with the subrepo upstream. This is arguably consistent with the git model writ large (make local commits, later choose if/how to integrate those with upstream). Importantly, people that clone your superproject repo don't have to know anything about subrepo or special commands to send changes back to you.

For submodules, changes flow in the other direction. If you want to make a change to the child repo, you must 1) commit in the submodule, 2) push the submodule commit to its upstream, 3) make a commit in the super project that changes the commit the submodule is pointing to. When someone pulls, switches branches, etc in the superproject, they need to do a submodule update with various failure modes or else they end up with empty/out-of-date content.

Subtrees are a bit similar to subrepos, but in practice you still need to be aware of their boundaries since you can't mix subtree/superproject modifications in the same commit. Moreover, you need to use a special merge strategy rather than git default merge/rebase which subrepo uses.

> I'd be happy to do something different, but I never had some idea that I could sell in a meeting, and didn't really have the energy or clout to fight this.

Would the alternative I suggested here work? I think you might even be able to do it in tandem with submodules so you try out both and see what works for you:

https://news.ycombinator.com/item?id=26165644

> pretty much can't fix... or with much difficulty.

I don't believe this for a second.

> Do you do things with git beside the trivial operations (add/commit/etc.)? Like rebasing/merging and such across commits that introduce or remove submodules?

Yes, often (I'm a stickler for clean histories on my projects). The trick is to only work with submodule refs during any sort of complex series of commands, then update the submodules once all of the ref munging is done.

If you have a ref conflict or something (rare IME, unless you're running git commands haphazardly, without understanding them), the error message tells you exactly which ref it couldn't check out and why - in which case, simply cd in and fix it manually.

If you need to move submodules around, `git submodule --deinit` it first, then re-add it.

If you need to remove one, deinit it then make sure it's purged from .gitmodules.

> Do you never encounter friction when e.g. removing submodules?

Nope, though admittedly the commands need some polish here. Worst case, remove the directory in the working tree, remove the entry from .gitmodules, delete .git/module/x/y/z/, then add -A the now-deleted worktree path and your .gitmodules.

> Do you never run into the errors people complain about?

Not since I sat down and read through the concepts section on the official Git docs, which outline what e.g. objects, trees, commits, tags and refs were, no.

Git submodules are up there on the list of the most misunderstood (but entirely useful) features ever, in my opinion.

> The trick is to only work with submodule refs during any sort of complex series of commands, then update the submodules once all of the ref munging is done.

So you don't actually check out the submodule, ok. But this means you can't actually use the correct submodule commit during the rebase? Like trying to build with it to check if it works before continuing?

> Nope, though admittedly the commands need some polish here. Worst case, remove the directory in the working tree, remove the entry from .gitmodules, delete .git/module/x/y/z/, then add -A the now-deleted worktree path and your .gitmodules.

How do you admit this and yet simultaneously say "I don't know why people raise such a stink about them" and "Not once have had issues with them"? You somehow know there are pain points, you know the various workarounds which can consist of N hoops to jump through, and yet you claim you haven't encountered issues even once and don't even understand what people dislike about submodules? Aren't these clearly contradictory?

> Not since I sat down and read through the concepts section on the official Git docs, which outline what e.g. objects, trees, commits, tags and refs were, no.

I'm pretty sure I know what all of those are and still find submodules painful.

> But this means you can't actually use the correct submodule commit during the rebase?

You can update during an interactive rebase if you need to, why not? I've never personally needed this but given how rebases work then an update should be possible if you need to.

> How do you admit this and yet simultaneously say "I don't know why people raise such a stink about them"

Because the lack of a simple removal command does not warrant the "avoid submodules at all costs" sentiment currently the top voted comment on this thread.

> You somehow know there are pain points, you know the various workarounds which can consist of N hoops to jump through,

There are places to improve commands. That's it. And the only hoop I have to jump through is a removal of a stubborn submodule the need arises.

> Aren't these clearly contradictory?

No. The world isn't a dichotomy; both things can be true.

> I'm pretty sure I know what all of those are and still find submodules painful.

A submodule is just a ref, just like a tag. Init and deinit can be finicky, that's about it. If you fully understood refs, then submodules shouldn't be that difficult to reason about.

What, specifically, do you find "painful"?

> You can update during an interactive rebate if you need to, why not?

You said your "trick" is to explicitly not update the submodules until you've finished the rebase? By definition that means you're not updating the submodules during the rebase...

> Because the lack of a simple removal command does not warrant the "avoid submodules at all costs" sentiment currently the top voted comment on this thread.

It's not just removal, though removal is definitely a big chunk of it. See last paragraph.

> No. The world isn't a dichotomy; both things can be true.

The world isn't a dichotomy, but you "admit the commands need some polish" and then propose a 4-step workaround for issues you've "not once had"? Did you not encounter issues at some point to lead you to propose workarounds and conclude commands need polishing?

> A submodule is just a ref, just like a tag. Init and deinit can be finicky, that's about it. If you fully understood refs, then submodules shouldn't be that difficult to reason about. What, specifically, do you find "painful"?

I don't think you understand how annoying it is for submodules not to add/remove/update seamlessly. Maybe you only use submodules for your own personal projects and rarely modify them so you rarely see the effect. But especially in a team project that's evolving constantly and the submodules aren't frozen, and especially in projects where you have to go mess with your own submodules to figure out if to-be-proposed changes to dependencies will actually do what you want, having to constantly go out of your way to make sure everything is committed and synced properly every single time you check out a new commit gets annoying fast. Especially when you don't even know what commits contain submodule changes to begin with.

You're assuming a lot about me so I don't really feel like spending time answering in depth. You seem to hold a strong opinion you're not willing to change, and while that's fine, I don't appreciate being told I'm somehow not qualified to have a differing opinion when that is very clearly not the case.

> You said your "trick" is to explicitly not update the submodules until you've finished the rebase? By definition that means you're not updating the submodules during the rebase...

A "trick", not a rule. If you need to check submodules during an interactive rebase, fine, do it. Nothing is stopping you, and it should work fine.

> The world isn't a dichotomy, but you "admit the commands need some polish" and then propose a 4-step workaround for issues you've "not once had"? Did you not encounter issues at some point to lead you to propose workarounds and conclude commands need polishing?

For 1 issue, of which I feel could definitely have a better command. You're arguing semantics at this point. I've not had issues where I'm so stuck they're impossible to use or to fix, like so many others here claim they do.

> I don't think you understand how annoying it is for submodules not to add/remove/update seamlessly.

I don't think you understand how submodules work, at all.

> Maybe you only use submodules for your own personal projects and rarely modify them so you rarely see the effect.

You assume incorrectly.

> But especially in a team project . . . and . . . projects where you have to go mess with your own submodules . . . having to constantly go out of your way to make sure everything is committed and synced . . . single time you check out a new commit

You're using submodules incorrectly, then. Learn what worktrees are if you don't. Learn what directory remotes are. Learn how to use multiple remotes, even.

None of what you're saying is a result of bad Git design. It's a result of you not knowing how Git works, or how to use it effectively. Git gives you all of the tools to use submodules effectively (e.g. testing changes without commiting, or testing changes directly in a submodule, etc.)

Do not patronize me because I RTFM.

Wow. I'm not "assuming" anything about you, I'm going literally off what you wrote ("I'm a stickler for clean histories on my projects" when I asked if you use git non trivially...) and even then I said maybe this is why, and even then its truth or falsehood had absolutely zero bearing on the correctness of my points. And that was literally just 1 thing, not "a lot". For someone trying to be accurate you exaggerate like there's no tomorrow, and that's been part of the very issue from the very beginning of the discussion.

Meanwhile the person who's been patronizing me and everybody else this entire time is you. Pretending like you're the only one who understands git and me and the rest of the world doesn't. You both go out of your way to trash my understanding of the entirety of git (not only do I not understand how submodules work but I don't understand remotes either? seriously?) with absolutely zero basis and also get offended that I said maybe you're simply not using git in the same kinds of projects that others do and hence that might be why you're not realizing why the problems are such a big deal to other people you've been looking down on before I even started replying? Your entire thesis is always that nobody but you has read the manuals or understood git, and yet I'm the one with a strong opinion unwilling to change? Really?

Yes, obviously I don't understand anything in git and the problem is in fact that nobody understands anything about git except you; it can't be any other way.

This is my experience too, I wouldn't recommend people use them unless they really understand the costs. The last time I used them was to help manage my dotfiles, so I could use them with Pathogen to pull in my selection of vim plugins. It was just a headache, to the point where I bit the bullet and went down the package manager (vim-plug) route instead.

This is also the only use-case I have for git sub-modules. However, I haven’t encountered any serious problems. I mostly leave my (few) Vim plugins alone for so long that I forget the git commands to update the plugins when I do decide to update them. Having to check my notes or the relevant section of the Git Book is the worst of the friction.

I’m using Pathogen as it works fine for me. I believe Vim 8.0 introduced something similar but I still have to use older Vim releases on various CentOS 6 and 7 systems.

I don't understand why submodules are so bad. They are a feature where maybe 60% is implemented, and then just abandoned.

Mercurial has subrepos, which are the EXACT same feature, but they are actually fully implemented, they work, and they don't make you shoot yourself in the foot constantly. They are mostly a joy to use.

Submodules used to be terrible to use but now that every tool supports it they are usable.

A lot of dependency managers are moving to supporting git repos which I think is great. An annoying thing about this though it is causes several round trips to origin that can be saved with submodules. It's never easy...

Its better to treat submodules as src dependencies and not wannabe mono-repo tool. Try not to change them. If you read-only they're somewhat painless.

Yeah, I agree. At some point in time I came up with a clear rule on when exactly submodules are the best solution, and it was such a narrow set of circumstances that I forget what it was at this point. I think it might have been in situations similar to Boost, where the project is actually modular? I forget. But even in those cases the friction is painful. (For the life of me I don't understand why they don't try to polish all the rough edges. Anyone know?)

One alternative solution I like: have a build tool that pulls dependencies in automatically. Bazel supports this natively, but I've also done this in plain ol' Make. Like you can build download rules for deps/github.com/% to automatically pull from GitHub, and the rest of the script can just treat them like local files. Having the build tool take care of it often seems to fit the problem space better too.

Your later half is essentially what subtree does, but it can also merge changes if you have any.

Wait really? I thought subtree stores a copy of the other repo?

Maybe I misunderstood and you aren't checking in those files, in which case it isn't the same.

Don't use subtrees, they're even worse. At least when we tried using them for a while before moving to submodules; perhaps they're less of a broken hack these days.

For example, whenever we did something with the subtree it reprocessed all commits in the repo - obviously taking longer and longer as time went on.

Submodules have been working very well for my emacs config for years now. However, I've used them for software projects and they are indeed awful. I joined a company where the lead engineer had set up a build system that was to be included as a submodule in every repository. It was a nightmare.

I have same experience with you, when I tried to deal with a c++ library that was co-developed with the main project.

In lieu of an ubiquitous package manager / module support what other options are there for c++? Keep a text file in the main project with the version of the library you need to compile it ?

Agree 100%. Submodules should be instead be implemented through auto-published library semver jars which are auto-incremented.

SAME exact experience here. If you can create either a build workflow or some other method of managing a relationship like this, do that instead of submodules.

I've been on teams that used it quite excessively and it was a PITA. I've used it in much smaller ways to try to avoid a build step or two and it worked until it was responsible for the world falling and no one knew it was that damn sub module.

Just because the tech exists, doesn't mean it's a good idea.

In my experience, such things tend to be misused when dependency management is not available. There are many tools today which sell themselves as "dependency managers" which are in fact just glorified downloaders. Such things should be called "download managers" instead.

This is beyond dramatic. To actually suggest copy/paste is preferable is asinine.

Once you get used to them, they are fine. I never have issues with submodules and I get to easily change revisions of dependencies.