Eww, a 20MB GIF with harsh dithering artefacts. And then another 22MB in two more GIFs. All in the repository.
(a) GIF is not the right format here, use a video format because it’ll produce a visually superior result (proper colour, no dithering needed—not that it actually is even with animated GIFs) and much more usable result (not autoplaying if the user agent’s configuration says not to, allowing scrubbing, showing how long the video is rather than you having to guess “is it still going, or did it start again?”, that kind of thing) in significantly less space.
(b) Things like this emphatically do not belong in the code repository, because they bloat things forever despite being for demonstration only. A repository that would have been 1.0MB and cloned in well under a second is instead 46.2MB (43.8MB of GIFs and 2MB of PNGs) and took me about fifteen seconds to clone (cloning repositories from GitHub is always slower than you’d expect when you’re on the other side if the world, in AU/NZ).
I believe the best practice is to use a dedicated "media" branch for screenshots/gifs/webp. Then you can use them on your readme like this .
You can rewrite history on the media branch so the files don't accumulate whenever you update them.
That’s still going to be included in a standard clone, though at least it makes it possible to do a partial clone and exclude that branch. rjzzleep is right to point out the wiki repository as a good place to store such things, still being a Git repository so that it need not be tied to GitHub, but there’s also the option these days of editing the README in GitHub’s web interface and uploading the images or videos through that, which stores it on GitHub servers outside the repository.
Hey, I'm the developer for nvui. I definitely messed up a bit putting the GIFs in the repo, I noticed it when the actions' build size increased by about 40MB (the display assets get removed now in the build). I don't know if there's a way to remove them now without removing a lot of the git history.
Also about the dithering, I'm aware that the GIFs look horrible, but that was not how they looked when I recorded them, I don't know if it was Github's compression but they look a lot worse when uploaded.
You can use BFG [1] or git-filter-branch to remove individual files from the history, though doing so will change the hash of every commit since the files were introduced. Whether it's worth the disruption or not is up to you.
No idea why he's getting downvoted but megabytes of GIFs absolutely don't belong in a code repo. Author could have just put a screenshot in there put the video inside the github .wiki.git repo.
EDIT: didn't think I have to clarify this, but when I say put a screenshot, I mean "A"(1) screenshot, if necessary.
Even the screenshots don’t belong in the code repository, there’s another 2MB in this instance. I think you can still get the README to embed images from elsewhere? And if not, just link to it, “screenshots over here”.
The compromises being made in bloating repositories because GitHub presents the README as project info rather than at least allowing you to separate it are painful.
What happens when the URLs referenced by the README stop existing (domain expiry)? What about when the project is forked? What happens when I want to look at old documentation locally?
Why should the entire project not be subject to version control? It's a well established industry best practice.
Reproducible documentation is just as important as reproducible builds.
There's likely a strong argument to be made for Git sub-modules though i.e. putting the documentation in a sub-module.
This particular content isn’t documentation so much as marketing material—part of the shift GitHub has foist upon us in what a README is. But even were it documentation, that needn’t belong in the same place. This is the wisdom of rjzzleep’s suggestion of the wiki repository, an auxiliary Git repository that GitHub already creates for you.
A screenshot or two, sure. And maybe chrismorgan's point could have been, well, perhaps expressed more gently. :) But the general point about multi-megabyte image files that are only there to enhance the README file perhaps not being ideal to have in your code repo, and something you could have on a separate non-repo page that goes into more detail, seems pretty reasonable.
Even when GitHub didn’t support embedded videos, large GIFs are awful enough that I insist that they had no place in READMEs, whether internal or external to the repository. In that time, it was far better to make it a link to something external.
The author deliberately added the files to the repository. That’s (part of) the problem. .gitignore is about saying “I don’t want to add matching files to the repository, so stop telling me they’re not in the repository”.
If it's not a problem, then I would say it's rude for potential users and bad practice for developers.
The README transfers almost 100mb. If I'm on my phone with no wifi and I see an interesting repo as I'm a neovim user, I will just lose 100mb from my data plan with no warning. One doesn't expect that when visiting the README of a code repository.
Then what happens when they change something that makes the gifs obsolete? Will they add a commit with updated gifs that doubles the size of the repository? Most developers use
git clone $URL
which copies the entire repo history, instead of using `--depth 1`. So now if someone wants to contribute a small change, they have to download hundreds of MBs of gifs.
Hi! I'm the developer of nvui. You were definitely right about the readme bloat. I've removed the GIFs in favor of videos uploaded to Github and links to them, although the GIFs may be stuck in the history.
(a) GIF is not the right format here, use a video format because it’ll produce a visually superior result (proper colour, no dithering needed—not that it actually is even with animated GIFs) and much more usable result (not autoplaying if the user agent’s configuration says not to, allowing scrubbing, showing how long the video is rather than you having to guess “is it still going, or did it start again?”, that kind of thing) in significantly less space.
(b) Things like this emphatically do not belong in the code repository, because they bloat things forever despite being for demonstration only. A repository that would have been 1.0MB and cloned in well under a second is instead 46.2MB (43.8MB of GIFs and 2MB of PNGs) and took me about fifteen seconds to clone (cloning repositories from GitHub is always slower than you’d expect when you’re on the other side if the world, in AU/NZ).