Docs tutorial: Git LFS
Problem to solve
Git LFS is increasingly important for our customers, because Git does not store large binary files well. Our documentation on Git LFS is fragmented and problematic, and should be cleaned up:
-
https://docs.gitlab.com/ee/topics/git/lfs/index.html is in
Build your application → Repositories
but doesn't talk about how to get started -
https://docs.gitlab.com/ee/topics/git/lfs/migrate_to_git_lfs.html is not in the nav because it's marked as outdated. It says to use
git lfs migrate
(https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.adoc) instead. - The migration page contains some links that we should revisit / determine if we should swipe info from:
Goals
- Ensure we answer some or all of these questions clearly and prominently:
- "I want to know how to set up Git LFS, so that I can keep the git database at a reasonable size even when the developers commit large files to it."
- "I want to know how to use Git LFS, so that I don't accidentally push a large file to the git database and slow down git for everyone else."
- "How do I set up my machine to use Git LFS?" (Sean pointed to https://docs.github.com/en/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage as inspiration)
- Remove the outdated migration page.
- Restructure
doc/topics/git/lfs/index.md
to follow CTRT guidelines, and provide a clearer path for users to get started with (or convert over to)git lfs
. Page should remain in its current location - Discuss with Support counterpart if additional information can be added to help reduce Support burden
Other links/references
This page has been brought up as problematic before.
- Related to Git LFS: Improve documentation (#385404 - closed) which was a KR for groupsource code that they declined to tackle due to load
- Related to FY23Q4 Create:Source Code KR: Improve LFS usabi... (create-stage#13084 - closed)
- Related to Disambiguates LFS pages, adds related topics (!107123 - merged) - a small merge request I did last month as a tiny stopgap
- Related to Document how the LFS calculations work with for... (#373832 - closed) - has more info about cleaning up deleted files that we can build into a tutorial
Edited by Amy Qualls