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.

I found this idea here: https://medium.com/@minamimunakata/how-to-store-images-for-u...

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.

[1]: https://rtyley.github.io/bfg-repo-cleaner/

Last I checked Github doesn't support embedded videos.

It's far from ideal, and I doubt anyone is claiming otherwise, but GIFs in Github READMEs are entirely standard practice.

EDIT: Well, there you go. Video was introduced within Github this year: https://github.blog/2021-05-13-video-uploads-available-githu...

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.

why don’t megabytes of gifs belong in git? you can use things like git-lfs if you don’t want the file updated with every change.

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.

I thought that embedding videos only works in issues and PRs, not Readmes?

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.

Forgive me if I'm missing something here, but can't you just add media files to .gitignore?

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”.

What problem? It’s their repo—they can add what they like…

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.

Hi! I'm the developer for nvui (didn't realize this post was made, never used this forum before). The animation durations and a few other things about them are customizable if you look into :h nvui-multigrid and :h nvui-cursor. As for the GIFs, I didn't expect them to come out badly (don't know if it was compression, but they didn't look that bad when I uploaded them. I'll look into making a "media" branch.

Hi and thanks! I'm a NixOS user and sloppily created a package but when I run I get "qt.qpa.wayland: EGL not available", probably an issue with my build.

Anyway, the default animation durations are IMO too long, at least the cursor animation, I couldn't make the window animations work, wonder if it's related to that error message.

[edit] nevermind, I see there's a released build so I'll just use that and go the patchelf route

Hi! If the animations are too long, you can shorten them. So for the cursor animation, the default is 0.3 seconds. You can shorten it to, let's say, 0.1 seconds by using the command

:NvuiCursorAnimationDuration 0.1

That'll reduce the duration to 0.1 seconds. The animation also runs at a specified frametime in ms (divide 1000 by FPS), default frametime is 10ms (so 100FPS). You can modify this using

:NvuiCursorFrametime 5, for example, for a 5ms frametime (200FPS).

I recommend that you try webp instead of gifs. they will probably look better.

Yes, if they're less than 100ms, sure - animations provide context to what's happening on the screen (human vision system likes to persist objects).

Any longer, and I want to throw the computer out of the window.

I’m not a UI/UX expert but here’s my 2¢ from limited work in this area. It depends on the type of animation and the platform. A fade in that’s 250 or even 500ms can be a nice effect on mobile when it’s not blocking other interactions. 100ms is too short to be noticeable for many things and depending on the screen refresh rate and distance for motion animations you will end up with large jumps.

I disagree. This is exactly what’s wrong with modern UX/UI. I abhor fading animations, they’re just decorations.