Simplify and deduplicate installation instructions #5260
Conversation
README.md
Outdated
| - Ensure you have the latest version of Go, GNU make, and a standard Unix-compatible build environment installed. | ||
| - On Windows, install `goversioninfo` with `go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest`. | ||
| - Run `make`. | ||
| - Place the `git-lfs` binary, which can be found in `bin`, on your system’s executable `$PATH` or equivalent. | ||
| - Git LFS requires global configuration changes once per-machine. This can be done by | ||
| running: |
There was a problem hiding this comment.
I think we'd like to keep these instructions on building from source, as they were specifically updated in PR #4527 to capture various details which aren't in the Wiki page, and which we'd like to have right up front for users. Would you mind restoring these in the From source section? (We should probably drop the unnecessary hyphen in "per-machine", though.)
There was a problem hiding this comment.
Hi @chrisd8088 Thank you for your review and feedback! 🙇♂️ ❤️
I found the wiki with the Installation instructions only at the end of performing my pull request changes (since it was only linked to from the "From source" section).
Now I have to ask, why are there installation instructions in the README and in the wiki? 😊
From the user perspective I find it quite confusing as you don't know which is the most up-to-date and the source of truth, from the maintainer perspective I also would find it as an unnecessary overhead?
Wouldn't it make sense to consolidate these instructions in one place? 🤔
(I'm happy to help with that.)
The overall goal would be to make it as easy and straight forward for users to install Git LFS and reduce confusion and friction.
There was a problem hiding this comment.
I would assume that different folks created the two sets of instructions at different times. I think it's probably advisable for the Wiki to refer to the canonical instructions in the repo's README.md rather than the other way around.
There was a problem hiding this comment.
I think it's probably advisable for the Wiki to refer to the canonical instructions in the repo's README.md rather than the other way around.
I agree! We can then link to the README from the wiki.
If it's 👍 for you I would work then on moving and consolidating the installation instructions in the README and update this PR accordingly.
There was a problem hiding this comment.
Well, I was only talking about the Wiki's copy of these particular notes, not the whole INSTALLING.md page, if that was what you were thinking. If you don't mind restoring these notes in the README.md, that would get my approval -- thank you!
There was a problem hiding this comment.
If you don't mind restoring these notes in the README.md, that would get my approval -- thank you!
Hi @chrisd8088,
In 6b2aa30 I have restored the "From source" section from the original README.md.
The only change I made is making git lfs install inline as suggested in #5260 (comment).
For convenience here is the updated rendered README.md:
https://github.com/steffen/git-lfs/blob/main/README.md
I think these changes should make the PR approvable.
As discussed, further potential improvements I will propose in separate bitesized pull requests over time.
Thank you again for your review and feedback! 🙇♂️
Co-authored-by: Chris Darroch <chrisd@apache.org>
Also make `git lfs install` code example inline.
Today I wanted to install Git LFS on a Linux-based system.
Unfortunately I had a hard time to find the complete installation instructions. 😩
Reproduction steps
I was happy to find a Linux users mention with a link to installation instructions on packagecloud.
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bashUnfortunately Git LFS was still not installed (I got
git: 'lfs' is not a git command. See 'git --help'.when runninggit lfs). 😢I then ran
apt-get install git-lfsfor which I got a permission error.sudo apt-get install git-lfswhich finally installed Git LFS on my Linux system. 😅Baffled by the unclear installation instructions I then found that there is a whole document dedicated to installing Git LFS on Linux:
https://github.com/git-lfs/git-lfs/blob/main/INSTALLING.md
This document is currently not linked to from the README (or the website at git-lfs.com).
Proposal☺️
I propose to simplify and deduplicate the README's installation instructions as well as adding the missing link to INSTALLING.md.
First I noticed that there is a Downloading section which starts with a "You can install ..." sentence and that there is a Installing section.
Both sections include information on installing from binary and from source, which seem to be redundant?
I therefore propose to consolidate the Downloading and Installing sections into one Installing section.
This is the main change proposal of this pull request besides adding a link to INSTALLING.md.
I also propose to make the INSTALLING.md document a little bit more clear.
I removed some redundant steps information in the beginning of the document and I added "1." and "2." numbering to the sections to make it clear there are two steps.
(I also lowercased some confusing uppercase mentions of apt and yum. 😊)
I
may also openhave opened a pull request for https://github.com/git-lfs/git-lfs.github.com to make these README installation instructions easier to discover: git-lfs/git-lfs.github.com#55