Binary files like PDF or images should be stored in git lfs. History should be rewritten
KOLANICH opened this issue · 6 comments
Hi. Could you move all the binary files into git lfs? Also I am not sure that storing PDF in the repo is a good approach. I prefer to store only sources in repos, and make CI to generate artifacts like PDF.
Sorry, I don’t know what you are talking about. What is “git Ifs”? And there is no CI available to do things like generate artifacts. This is the approach I use in a number of my repos, and I don’t have any plans to change it, except that maybe someday I will move to Antora for building integrated documentation sites.
Also, rewriting history for things that have been pushed off a local machine should never happen.
What is “git Ifs”?
A tool from GitHub team to handle binary files more efficiently. For windows it is shipped with git for Windows, for Linux install git-lfs package. Then git lfs install and git lfs track *.pdf *.jpg *.png and any other binary files you want to keep in the repo.
And there is no CI available to do things like generate artifacts.
GitLab CI is available. There is also GitHub Pipelines, but it is in beta and requires signing NDA, I have not used it personally.
Also, rewriting history for things that have been pushed off a local machine should never happen.
Your repo has no forks, so IMHO it is completely OK.
You need to recreate the repo from scratch, activating lfs first, or use git lfs migrate.
Unfortunately this is by far the newest repo in this constellation of projects. dysentery, which uses the exact same LaTeX/PDF setup, has forks, and afterglow, which has a large number of images in the online documentation, has even more. Still, worth exploring. Two questions I have:
- GitLab CI offers hosts to run commands? Can they run LaTeX?
- If I have images in Git LFS, can they still be viewed in GitHub hosted AsciiDoc documentation? That is their primary function in my repositories, to be viewed on GitHub.
In any case, I would have to figure out how to install it on the Mac if I wanted to move forward with it, but I am sure I could. That would make it harder for anyone who wanted to check out the repositories as well, though?
GitLab CI offers hosts to run commands? Can they run LaTeX?
Yes, you need to choose a docker image first. GL CI is centered around docker images: you usually need an image with all the tools you need preinstalled. I used to use miktex/miktex, and it worked fine for some time, but one day it had stopped working (they have changed the default user, so apt-get needed for installation of fonts stopped working), then I have created an issue. Recently they have fixed that issue, but somehow my build is still broken (fonts are installed fine, but xelatex execution fails) and I don't have time to debug that for now. Currently I don't know how to fix that: on a local machine my docs are built fine. Anyway, here is the .gitlab-ci.yml I use, feel free to reuse.
If I have images in Git LFS, can they still be viewed in GitHub hosted AsciiDoc documentation?
It seems, that no: git-lfs/git-lfs#2725 . GH doesn't automatically resolve files stored in LFS.
Ok, so I won’t use Git LFS, since it would prevent the images from serving their purpose. But the images don’t change often and are not large, and they are the “source” for the documentation, so they are not a problem. The PDF does get large and does change often, so I have simply removed it from git control, and now host it on my own web server. Since I am using some local fonts (purchased from Adobe, which I cannot host in a public repository) with XeLaTeX, for now I will just manually scp the PDF rather than trying to figure out GitLab CI. But it is something interesting to keep an eye on.