Switch documentation to AsciiDoc #5054
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Our current manual pages use ronn or ronn-ng, which converts pages from a superset of Markdown into manual pages or HTML. This mostly works, but it has some limitations: * ronn-ng requires several dependencies, some of which are C based, which means we must build those on older version of RHEL-compatible OSes. This adds a substantial amount of porting hassle and time to the build. * The superset of Markdown that ronn-ng uses is not rendered correctly on GitHub, leading to difficulties when people view manual pages in the web interface. * Markdown, and the superset ronn-ng uses, don't contain description lists, which are useful for both command options and items in the FAQ, which we'd like to ship in the package. Instead of using Markdown, let's switch to AsciiDoc as the format for manual pages. Asciidoctor, the Ruby version of the command, is written in pure Ruby and is self-contained, and supports HTML 5, XHTML 5, man, and DocBook 5 all in a single program. In addition, it is the library used for rendering AsciiDoc on GitHub, which means that whatever syntax we use is fully supported and should render properly. This commit introduces a simple conversion as the first step, which we'll fix up in several subsequent commits. The Markdown pages remain for now and will be removed in a later commit. This conversion was done using Debian's pandoc 2.9.2.1-3+b2 using the following command: (for i in *.ronn; do pandoc -f commonmark -t asciidoc -o $(basename $(basename $i .1.ronn) .5.ronn).adoc $i; done) Note that during our conversion we remove the number in the manual page name, since Asciidoctor will emit this automatically and we don't want a trailing ".1.1" or ".5.5".
In the conversion from Markdown to AsciiDoc, we used pandoc's CommonMark converter. That converter treats most entries in angle brackets as HTML tags, unlike ronn-ng, and therefore eliminates them from our synopses. Let's restore them back to where they were before so that they make sense. At the same time, make sure our synopses contain the required plus signs if we'd like a hard line break, even if they did not contain one before.
When pandoc did our conversion to AsciiDoc, it was not aware that we were working with manual pages. Automatic handling of manual pages with Asciidoctor requires that the title of the manual page be a top-level, not a second-level, title, and that the name section be explicitly specified. Let's fix our manual pages to meet that standard automatically with the following shell command. This has the pleasant side effect of also normalizing whether we use one or two dashes between the name and the description to a single dash, which is what the Git manual pages use. ruby -pi -e '$_.gsub!(/^(=+)=( \S)/, "\\1\\2")' \ -e '$_.gsub!(/^= (\S+)(\(\d\)) -+ (.*)$/, "= \\1\\2\n\n== NAME\n\n\\1 - \\3")' \ *.adoc
Because Markdown lacks description lists, ronn converts bulleted lists with options in them into an appropriate entry in the manual page. However, AsciiDoc has description lists, so let's convert the values we got from the ronn source to actual description lists. Do this with the following one-liner: ruby -pi -e '$_.gsub!(/^\* `(-.*)`\s+`(-.*)`(.*):(.*)$/, "\\1::\n\\2\\3::\n \\4")' \ -e '$_.gsub!(/^\* `(-.*)`(.*):$/, "\\1\\2::")' \ -e '$_.gsub!(/^\* `(-.*)`(.*):\s+(.*)$/, "\\1\\2::\n \\3")' \ -e '$_.gsub!(/^\* (-.*):$/, "\\1\\2::")' \ -e '$_.gsub!(/^\* (-.*):\s+(.*)$/, "\\1::\n \\2")' *.adoc
In the git-lfs manual page, switch the AsciiDoc to use definition lists instead of the bullets, since ronn converted these automatically into definition lists.
When we autoconverted the ronn source to AsciiDoc, we used the CommonMark converter, since there isn't a ronn-specific one. However, that caused some problems because anything in angle brackets was assumed to be an HTML tag and removed. Fix all of the options descriptions that had a missing argument by restoring the argument to what it was before.
While Asciidoctor will accept inconsistent indentation for our definition lists, this makes it hard to read in the plain text format. Since the text we embed in the manual pages is the source, it would be nice to have a consistent indentation for ease of reading by users. Therefore, indent each of our definition lists such they are properly indented to two spaces. For some items which should have been definition lists, but, due to syntactic anomalies, didn't get converted, convert those to definition lists and properly indent them as well.
We normally write options as lowercase text with angle brackets, so do that here as well.
In this case, the conversion to AsciiDoc has removed a line break which we want. Make this work properly by using a source block.
Restore text that was removed by the conversion to AsciiDoc.
Asciidoctor provides autogenerated IDs for all section titles. Use these for our cross-references and replace the old ronn-style internal links. While we're at it, clean up a few small issues like indentation.
Member
Author
|
I'll just say that I'm fully aware that this is a giant series of commits and that it's fine to take whatever time you need reviewing this. I'll stuff in the FAQ and some doc updates in a future series. |
chrisd8088
approved these changes
Jun 30, 2022
Member
chrisd8088
left a comment
chrisd8088
left a comment
There was a problem hiding this comment.
Fantastic and comprehensive, thank you!
docs/man/git-lfs-fetch.adoc
Outdated
Comment on lines
24
to
25
| -X <paths>:: | ||
| --exclude=<paths>:: |
Member
There was a problem hiding this comment.
Just as a minor note, this change to include the missing <paths> arguments technically fits better with the prior commit named doc: fix excluded parameters in options.
docs/man/git-lfs-unlock.adoc
Outdated
Comment on lines
19
to
20
| -r <name>:: | ||
| --remote=<name>:: |
Member
There was a problem hiding this comment.
Again, just the very minor note that the addition of the <name> argument would fit in the doc: fix excluded parameters in options commit.
docs/man/git-lfs-ls-files.adoc
Outdated
|
|
||
| == OPTIONS | ||
|
|
||
| -l:: |
Member
There was a problem hiding this comment.
I think a number of these kinds of single-character options without any arguments may have been missed in this conversion to add enclosing backticks. Maybe using the command below with [^:]* instead of [^:]+ would work?
ruby -pi -e '$_.gsub!(/^(-[-A-Za-z][^:]*)::$/, "`\\1`::")' *.adoc
| for f in $$(cd docs/man && ls git-lfs*.ronn); do \ | ||
| l=$$(printf "$$f" | sed -E 's/\.([1-9])\.ronn$$/(\1)/'); \ | ||
| printf "%s %s\n" "$$l $$f"; \ | ||
| done >>index.txt; \ |
Member
There was a problem hiding this comment.
I think there's a couple of lines in .gitignore which could profitably be removed since index.txt is no longer generated for ronn:
# only allow man/*.\d.ronn files
man/*
index.txt
These could just be:
man/*
Our options should be in monospace since they're thing that people will type at the command line. Convert all of our AsciiDoc files with the following one-liner: ruby -pi -e '$_.gsub!(/^(-[-A-Za-z][^:]*)::$/, "`\\1`::")' *.adoc
Now that we're converting our manual pages to AsciiDoc, let's use these versions as the input when generating our manual pages. As a result, there are some changes to the generator: * Our links look different than before, so handle AsciiDoc cross-references. If there's an actual description, use it; otherwise, take the link target generated by Asciidoctor and convert it to a string. Don't try to parse the actual title since that would make our parser not one-pass. * Use different header regexes since the headers are different. * Since we now have two types of source blocks, those with dots and those with dashes and a header, convert both types of blocks. If there is a header, remove it, and then strip off the delimiter lines. * Since we now have definition lists, handle both bulleted lists and definition lists the same way for indenting. Stop the indenting at a blank line, but do continue indenting when we receive the plus sign that indicates the continuation of the block. * Clean up the extra colon at the end of definition lists. * Clean up the space-plus that indicates a line break.
Now that we have AsciiDoc manual pages, let's build our manual pages from them. Stop building the index.txt file and use Asciidoctor to build the output instead. Handle the difference in file names gracefully. Finally, use the attribute "reproducible" to avoid outputting dates in our output and make them reproducible. Packagers will appreciate this.
The version ID set right now is a value like "8.5" on Rocky Linux 8. In such a situation, it's hard to compare, and this prevents rubygems-devel from being installed properly in such a situation. To make things work properly, strip off the decimal point and decimal value from the end of the string.
Since we're now generating our manual pages with Asciidoctor, let's depend on it instead of ronn.
If Asciidoctor is not already present, build the gem as an RPM.
Update all the dependencies to refer to Asciidoctor instead and remove the remaining ronn-related instructions and specs.
Use Asciidoctor instead of ronn to build docs.
These are no longer needed, so let's remove them.
Since we're no longer using ronn, let's remove the patterns and comments for it in `.gitignore`.
algitbot
pushed a commit
to alpinelinux/aports
that referenced
this pull request
Feb 10, 2025
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In commit 8945cbf of PR git-lfs#5054 we ceased using the "ronn" Ruby gem to generate our manual pages from their source files, and so the RONN* variables in our Makefile are no longer used and can now be removed.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In the manual page for our git-lfs-pull(1) command we provide an explanation that the command is equivalent (at least, in most cases) to running "git lfs fetch" followed by "git lfs checkout". When we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, the two example commands were accidentally merged onto a single line, and the "<remote>" option for the "git lfs fetch" command was elided. We therefore restore the original version of these two example commands, and add leading shell prompt indicators to further clarify that the example includes two separate commands.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page. We now restore another missing term, this time in the description section of the git-lfs-checkout(1) manual page, where the "<glob-pattern>" term was accidentally removed. We also take the opportunity to rephrase the sentence containing this term slightly so as to avoid the use of a trailing plural "s" character, as that causes formatting errors when rendering the AsciiDoc source into HTML or roff.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page, and in a prior commit in this PR we restored another in the git-lfs-checkout(1) manual page. We now restore another missing term, this time in the git-lfs-config(5) manual page, in the entry for the "lfs.customtransfer.<name>.path" configuration option, where the "<name>" term was accidentally removed from a sentence in which it was the first word. We also take the opportunity to add a leading definite article to the sentence so to make it slightly more idiomatic and readable.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page, and in prior commits in this PR we restored several others in the git-lfs-checkout(1) and git-lfs-config(5) manual pages. We now restore another missing term, this time in the description section of the git-lfs-smudge(1) manual page, where the "<path>" term was removed from the sentence which explained the purpose of the "git lfs smudge" command's optional progress log file path argument.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-migrate(1) manual page, the description text of the entry for the --skip-fetch option to the "git lfs migrate" command was fully indented except for the final line, likely because it begins with a monospace delimiter, so we adjust that now. Similarly, the second line of the description of the --theirs option in the git-lfs-checkout(1) manual page is not indented to match the first line, so we add the indentation now.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In our git-lfs-prune(1) manual page we dedicate one section to a explanation of how the Git LFS client determines whether an object is sufficiently "recent" to be retained and not pruned. In this section we list the Git configuration options that control the expiry and retention periods for objects, including settings such as "lfs.fetchRecentCommitsDays", "lfs.fetchRecentRefsDays", and "lfs.pruneOffsetDays". The list contains two entries, one for the "lfs.pruneOffsetDays" option and one for three of the "lfs.fetchRecent*" options. When the git-lfs-prune(1) manual page was first added in commit bd72983 of PR git-lfs#742, this list of the Git configuration options was formatted such that each entry began with the option name or names as headers on separate lines, followed by a description of their effects as a separate paragraph. When we converted our manual pages from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, the list was formatted as an unordered list where the option name or names and the subsequent description were simply all placed together as a single paragraph. To help make this section of the git-lfs-prune(1) manual page slightly more readable, we adjust its formatting now to use an AsciiDoc description list rather than an unordered list. By doing so, we can restore the option names as distinct headers, each of which will appear on a separate line when we render the source file into HTML or roff with Asciidoctor. The description text of each entry will also then be rendered as an indented paragraph following the entry's headers.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In our git-lfs-migrate(1) manual page, one of the entries in the list of options supported by the "git lfs migrate info" subcommand describes the --unit option, and enumerates the set of storage capacity units that we accept for that option. In this option's entry we provide two lists, one of decimal SI units (e.g., kb, MB) and one of binary IEC units (e.g., KiB, MiB), with the intent that they should each form a single entry in a second-level list nested within the top-level list of command options. However, when we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, this second-level list was flattened into continuous text, so we restore it now. In this commit we simply match the formatting already in use in several second-level lists in the git-lfs-config(5) manual page, although it does not render properly in any of our output formats. In a subsequent commit in this PR we will further update all of these second-level lists so they render correctly when converted to HTML and roff by Asciidoctor. We will also revise our "mangen" program so it supports second-level lists in the plain-text versions of our manual pages that it generates.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-logs(1) and git-lfs-pre-push(1) manual pages, though, the list of options were accidentally left formatted as unordered lists rather than description lists, so we revise them now to match the description list format we use in the manual pages for our other commands.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-track(1) manual page, though, the second colon character was accidentally omitted from the term of the final entry in the list of command options. Specifically, because the entry for the --no-modify-attrs option lacks a full term delimiter, it does not render properly when converted to HTML or groff, so we correct this problem now.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
May 15, 2025
The synopsis sections of our manual pages have generally been formatted in the same way since 2014, when our first manual page was added in commit 79518af of PR git-lfs#58. The fixed portions of the Git LFS command presented in each page's synopsis is delimited with backticks, and the remainder of the command is left unformatted. Our manual page source files were originally written in Ronn and now use AsciiDoc markup instead. In both cases, text delimited with backticks is displayed in a monospace font when our pages are rendered into HTML. This in itself is consistent with the style we use throughout our manual pages, as we aim to render all literals as monospace text. However, we also render all command option flags and argument placeholder names as monospace text, except within the majority of our synopsis blocks, where these are displayed in a proportional font. There are some exceptions, such as in our git-lfs-completion(1), git-lfs-filter-process(1), and git-lfs-pointer(1) pages, where the entirety of each line of the synopsis is rendered as monospace text, which is more consistent with how we display command arguments and flags in the other sections of our manual pages. Even in these cases, though, each line of the synopsis is rendered separately, because we have not placed the entire synopsis within a literal block. To prevent the lines being displayed as a continuous single line, we add trailing hard line breaks in the form of a space character and a plus ("+") character at the end of the lines. This is a fragile syntax, though, as can be illustrated by the current state of our git-lfs-push(1) manual page, where some hard line breaks were inadvertently omitted when additional lines describing the command's new --stdin option were inserted into the page's synopsis in commit e35f407 of PR git-lfs#5086. We can avoid these types of issues and format our synopsis sections in a manner consistent with the rest of our manual page text by using AsciiDoc source listing blocks with custom subtitutions. We place all of the command prototypes in each synopsis section into a single block, which means we can eliminate the trailing hard line breaks completely. By using source listing blocks we can support two additional features which should improve the readability of our manual pages' synopses. First, we can apply the "quotes" substitution rule, which means we can format the fixed portions of each command line such that they will be displayed as bold text when rendered into HTML. This formatting aligns with the convention seen used by many Unix manual pages, and also those of the Git project. The other feature we can now easily make use of in our synopsis blocks is the ability to break a single command prototype onto multiple lines, by indenting the second and subsequent lines so they are clearly identifiable as parts of a single prototype. In several subsequent commits in this PR we will revise some command prototypes so they are long enough that they will need to be split onto multiple lines, at which point the ability to indent lines within a single listing block will be highly advantageous. Since commit f11d309 of PR git-lfs#5054 our "mangen" utility has recognized AsciiDoc source listing blocks and rendered them into plain text appropriately. (Note that we use the "mangen" utility to convert our manual page source files into formatted plain text encapsulated in Go string assignments, which are then output by the "git lfs help" command.) We expect that in a subsequent commit in this PR we will modify the "mangen" program to ignore the asterisk character when it appears at the start or end of a Git LFS command in the new source listing blocks in our synopsis sections, as for the moment these asterisks will be rendered literally in the plain text output. As well, we also expect that in another commit in this PR we will introduce a small Asciidoctor extention module that will remove the indentation the current Asciidoctor "manpage" converter always sets for source listing blocks, but only for the blocks in our synopsis sections. This should prevent the synopsis prototypes from appearing indented by an extra amount when we render our manual page source files into the roff format.
chrisd8088
added a commit
to chrisd8088/build-dockers
that referenced
this pull request
Jun 18, 2025
In PR git-lfs/git-lfs#5054 we updated the source files of the manual pages for the Git LFS client from the Ronn format to the AsciiDoc format, which necessitated changing our Linux package build processes to use the Asciidoctor Ruby gem to generate manual pages in Roff and HTML formats. At the time, an RPM package for a 2.0.x version of the Asciidoctor Ruby gem was not easily available for all the platforms based on Red Hat Enterprise Linux (RHEL) that we supported, particularly RHEL/CentOS 7, so in commit git-lfs/git-lfs@db9a821 of PR git-lfs/git-lfs#5054 we updated the "rpm/build_rpms.bsh" script in our main project's repository to build and install a custom RPM package with Asciidoctor v2.0.17. In the same commit we also defined a SPEC file for this custom rubygem-asciidoctor RPM package in the "rpm/SPECS" directory in our main project. However, as noted in commit cfde130 of PR git-lfs#71, all the distribution versions based on RHEL 7, CentOS 7, and SUSE Linux Enterprise Server (SLES) 12 for which we previously built RPM packages have now reached the end of their standard LTS (Long-Term Support) periods, and so future releases of the Git LFS client will no longer build packages for them. This change means we will not need to build and install a custom RPM package for Asciidoctor any more, because there are rubygem-asciidoctor packages available in the Extra Packages for Enterprise Linux (EPEL) collection which provide Asciidoctor v2.0.15 or higher for each of the RHEL/CentOS 8, RHEL/Rocky Linux 9, and RHEL/Rocky Linux 10 platforms. We therefore update our Dockerfiles for these platforms to install the rubygem-asciidoctor package. As this package is available from the EPEL collection, we first need to enable the PowerTools (for RHEL/CentOS 7) or CodeReady Linux Builder (CRB) repository, and then install the EPEL package, before installing the rubygem-asciidoctor package. See, for reference: https://docs.fedoraproject.org/en-US/epel/getting-started/ https://packages.fedoraproject.org/pkgs/rubygem-asciidoctor/rubygem-asciidoctor/ Once this PR is merged, we can then update the "rpm/build_rpms.bsh" script in our main project so it skips trying to build or install a custom RPM package for Asciidoctor, and we can remove the corresponding SPEC file for that package as well.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Jun 19, 2025
In PR git-lfs#5054 we updated the source files of our manual pages from the Ronn format to the AsciiDoc format, which necessitated changing our Linux package build processes to use the Asciidoctor Ruby gem to generate manual pages in Roff and HTML formats. At the time, an RPM package for a 2.0.x version of the Asciidoctor Ruby gem was not easily available for all the platforms based on Red Hat Enterprise Linux (RHEL) that we supported, particularly RHEL/CentOS 7, so in commit db9a821 of PR git-lfs#5054 we updated the "rpm/build_rpms.bsh" script to build and install a custom RPM package with Asciidoctor v2.0.17. In the same commit we also defined a SPEC file for this custom rubygem-asciidoctor RPM package in the "rpm/SPECS" directory. However, we have now removed the Dockerfile we used to build packages for the RHEL/CentOS 7 and SLES 12 platforms in commit git-lfs/build-dockers@cfde130 of PR git-lfs/build-dockers#71, because all the distribution versions based on RHEL 7, CentOS 7, and SUSE Linux Enterprise Server (SLES) 12 for which we previously built RPM packages have now reached the end of their standard LTS (Long-Term Support) periods, and so future releases of the Git LFS client will no longer build packages for them. Further, in PR git-lfs/build-dockers#73 we updated the Dockerfiles we use to build RPM packages of the Git LFS client on the RHEL/CentOS 8, RHEL/Rocky Linux 9, and RHEL/Rocky Linux 10 platforms so that the rubygem-asciidoctor package is installed before the final command in the Dockerfiles is run. This rubygem-asciidoctor package provides Asciidoctor v2.0.15 or higher, so we no longer need to build and install a custom RPM package in order to use Asciidoctor to generate manual pages formatted in Roff and HTML. We can therefore now delete our custom SPEC file for the rubygem-asciidoctor package, and also simplify our "rpm/build_rpms.bsh" script by removing the section which built and installed our custom RPM package if the "asciidoctor" command was not found in a given Docker container image for an RHEL-based platform.
chrisd8088
added a commit
to chrisd8088/build-dockers
that referenced
this pull request
Jun 19, 2025
In PR git-lfs/git-lfs#5054 we updated the source files of the manual pages for the Git LFS client from the Ronn format to the AsciiDoc format, which necessitated changing our Linux package build processes to use the Asciidoctor Ruby gem to generate manual pages in Roff and HTML formats. At the time, an RPM package for a 2.0.x version of the Asciidoctor Ruby gem was not easily available for all the platforms based on Red Hat Enterprise Linux (RHEL) that we supported, particularly RHEL/CentOS 7, so in commit git-lfs/git-lfs@db9a821 of PR git-lfs/git-lfs#5054 we updated the "rpm/build_rpms.bsh" script in our main project's repository to build and install a custom RPM package with Asciidoctor v2.0.17. In the same commit we also defined a SPEC file for this custom rubygem-asciidoctor RPM package in the "rpm/SPECS" directory in our main project. However, as noted in commit cfde130 of PR git-lfs#71, all the distribution versions based on RHEL 7, CentOS 7, and SUSE Linux Enterprise Server (SLES) 12 for which we previously built RPM packages have now reached the end of their standard LTS (Long-Term Support) periods, and so future releases of the Git LFS client will no longer build packages for them. This change means we will not need to build and install a custom RPM package for Asciidoctor any more, because there are rubygem-asciidoctor packages available in the Extra Packages for Enterprise Linux (EPEL) collection which provide Asciidoctor v2.0.15 or higher for each of the RHEL/CentOS 8, RHEL/Rocky Linux 9, and RHEL/Rocky Linux 10 platforms. We therefore update our Dockerfiles for these platforms to install the rubygem-asciidoctor package. As this package is available from the EPEL collection, we first need to enable the PowerTools (for RHEL/CentOS 7) or CodeReady Linux Builder (CRB) repository, and then install the EPEL package, before installing the rubygem-asciidoctor package. See, for reference: https://docs.fedoraproject.org/en-US/epel/getting-started/ https://packages.fedoraproject.org/pkgs/rubygem-asciidoctor/rubygem-asciidoctor/ Once this PR is merged, we can then update the "rpm/build_rpms.bsh" script in our main project so it skips trying to build or install a custom RPM package for Asciidoctor, and we can remove the corresponding SPEC file for that package as well.
chrisd8088
added a commit
that referenced
this pull request
Oct 16, 2025
In commit 5aa7be5 of PR #5796 we added tests of the sparse checkout support provided by our "git lfs checkout" and "git lfs pull" commands, which makes use of the "git ls-files" command and the --sparse option that was introduced for that command in Git v2.35.0. In practice, the "git lfs checkout" and "git lfs pull" commands require Git v2.42.0 or higher to be available before they invoke "git ls-files", and otherwise fall back to using the "git ls-tree" command. We require at least Git v2.42.0 because that version introduced support for the "objecttype" field name in the "git ls-files" command's --format option and we depend on that field to be able to mimic the output format of the "git ls-tree" command with the "git ls-files" command. We noted these details in commit beae114 of PR #5699, when we revised the runScanLFSFiles() function in our "lfs" package to choose between the use of "git ls-files" and "git ls-tree". One difference between the "git ls-files" and "git ls-tree" commands, however, is that the former lists the files in the Git index (since we always pass the --cached option) while the latter lists the files in the Git tree associated with a given reference, which in the case of our "git lfs checkout" and "git lfs pull" commands is always the current "HEAD" symbolic reference. As a consequence, as discussed in issue #6004, if certain files are absent from the current working tree and Git index as the result of a partial clone or sparse checkout, the behaviour of the "git lfs checkout" and "git lfs pull" commands varies depending on the installed version of Git. If Git v2.42.0 or higher is installed, the "git lfs checkout" and "git lfs pull" commands invoke the "git ls-files" command and provide an "attr:filter=lfs" pathspec so the Git command will filter out files which do not match a Git LFS filter attribute. However, in order to be reported, Git LFS pointer files must exist in the Git index; if they only appear in the working tree or the Git tree associated with the "HEAD" reference, they will be ignored. (Note that in a non-bare repository, the "git ls-files" command will only match the "attr:filter=lfs" pathspec against attributes defined in ".gitattributes" files in the index or working tree, plus any local files such as the "$GIT_DIR/info/attributes" file. Any ".gitattributes" files that are present only in the Git tree associated with the "HEAD" reference will not be consulted. In a bare repository, meanwhile, the "git ls-files" command will by default not match the pathspec against attributes defined in ".gitattributes" files at all, regardless of whether such files exist in the index or in the tree referenced by "HEAD".) If a version of Git older than v2.42.0 is installed and so the "git ls-tree" command is invoked instead of the "git ls-files" command, then a full list of the files in the tree-ish referenced by "HEAD" is returned. The "git lfs checkout" and "git lfs pull" commands will then attempt to check out the Git LFS objects associated with all the Git LFS pointer files found in this list. In the case of the "git lfs pull" command, it will also try to fetch those objects if they are not already present in the local storage directories. (Note, though, that when the "git lfs checkout" and "git lfs pull" commands retrieve a list of files using the "git ls-tree" command, they do not check whether the pointer files they find in that list actually match Git LFS filter attributes in any ".gitattributes" or other Git attributes files. So a user may remove all the ".gitattributes" files from their working tree and index, commit those changes to "HEAD", and the Git LFS commands will still attempt to check out objects for any files found in the "HEAD" commit's tree that can be parsed as valid pointers. When the "git ls-files" command is used instead of the "git ls-tree" command to retrieve a file list, this legacy behaviour does not occur, because the "attr:filter=lfs" pathspec requires that the "git ls-files" command only return a list of files which match at least one Git LFS filter attribute.) In subsequent commits we will alter how the "git lfs checkout" and "git lfs pull" commands operate within bare repositories and how they handle file paths, including by changing the current working directory to the root of the current working tree, if one is present. Of necessity, our tests and documentation will also be expanded to reflect the variable behaviour of the "git lfs pull" command in particular, since its effects in a bare repository depend in part on the installed version of Git. Before we make these changes, we first revise our existing tests of the "git lfs checkout" and "git lfs pull" commands with partial clones and sparse checkouts so that the tests confirm the key differences in behaviour when the installed version of Git is v2.42.0 or higher. Our tests now demonstrate that with an older version of Git, objects will be fetched (in the case of the "git lfs pull" command) and checked out for all Git LFS files, including those outside the configured sparse cone. We also update the manual pages for these commands to include an explanation of how their operation varies depending on the installed version of Git, how this may affect repositories with partial clones and sparse checkouts, and the options available to users if they find the "git lfs checkout" and "git lfs pull" commands appear to be ignoring certain files. As well, we edit the initial section in our git-lfs-pull(1) manual page where we incorrectly state that the command is always equivalent to running "git lfs fetch" followed by "git lfs checkout", and fix the formatting of the example commands provided in this section. When we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR #5054, the two example commands in this section were accidentally merged onto a single line, and the "<remote>" option for the "git lfs fetch" command was elided. We therefore restore the original version of these two example commands and add leading shell prompt indicators to further clarify that the example includes two separate commands.
chrisd8088
added a commit
that referenced
this pull request
Oct 16, 2025
In commit 5aa7be5 of PR #5796 we added tests of the sparse checkout support provided by our "git lfs checkout" and "git lfs pull" commands, which makes use of the "git ls-files" command and the --sparse option that was introduced for that command in Git v2.35.0. In practice, the "git lfs checkout" and "git lfs pull" commands require Git v2.42.0 or higher to be available before they invoke "git ls-files", and otherwise fall back to using the "git ls-tree" command. We require at least Git v2.42.0 because that version introduced support for the "objecttype" field name in the "git ls-files" command's --format option and we depend on that field to be able to mimic the output format of the "git ls-tree" command with the "git ls-files" command. We noted these details in commit beae114 of PR #5699, when we revised the runScanLFSFiles() function in our "lfs" package to choose between the use of "git ls-files" and "git ls-tree". One difference between the "git ls-files" and "git ls-tree" commands, however, is that the former lists the files in the Git index (since we always pass the --cached option) while the latter lists the files in the Git tree associated with a given reference, which in the case of our "git lfs checkout" and "git lfs pull" commands is always the current "HEAD" symbolic reference. As a consequence, as discussed in issue #6004, if certain files are absent from the current working tree and Git index as the result of a partial clone or sparse checkout, the behaviour of the "git lfs checkout" and "git lfs pull" commands varies depending on the installed version of Git. If Git v2.42.0 or higher is installed, the "git lfs checkout" and "git lfs pull" commands invoke the "git ls-files" command and provide an "attr:filter=lfs" pathspec so the Git command will filter out files which do not match a Git LFS filter attribute. However, in order to be reported, Git LFS pointer files must exist in the Git index; if they only appear in the working tree or the Git tree associated with the "HEAD" reference, they will be ignored. (Note that in a non-bare repository, the "git ls-files" command will only match the "attr:filter=lfs" pathspec against attributes defined in ".gitattributes" files in the index or working tree, plus any local files such as the "$GIT_DIR/info/attributes" file. Any ".gitattributes" files that are present only in the Git tree associated with the "HEAD" reference will not be consulted. In a bare repository, meanwhile, the "git ls-files" command will by default not match the pathspec against attributes defined in ".gitattributes" files at all, regardless of whether such files exist in the index or in the tree referenced by "HEAD".) If a version of Git older than v2.42.0 is installed and so the "git ls-tree" command is invoked instead of the "git ls-files" command, then a full list of the files in the tree-ish referenced by "HEAD" is returned. The "git lfs checkout" and "git lfs pull" commands will then attempt to check out the Git LFS objects associated with all the Git LFS pointer files found in this list. In the case of the "git lfs pull" command, it will also try to fetch those objects if they are not already present in the local storage directories. (Note, though, that when the "git lfs checkout" and "git lfs pull" commands retrieve a list of files using the "git ls-tree" command, they do not check whether the pointer files they find in that list actually match Git LFS filter attributes in any ".gitattributes" or other Git attributes files. So a user may remove all the ".gitattributes" files from their working tree and index, commit those changes to "HEAD", and the Git LFS commands will still attempt to check out objects for any files found in the "HEAD" commit's tree that can be parsed as valid pointers. When the "git ls-files" command is used instead of the "git ls-tree" command to retrieve a file list, this legacy behaviour does not occur, because the "attr:filter=lfs" pathspec requires that the "git ls-files" command only return a list of files which match at least one Git LFS filter attribute.) In subsequent commits we will alter how the "git lfs checkout" and "git lfs pull" commands operate within bare repositories and how they handle file paths, including by changing the current working directory to the root of the current working tree, if one is present. Of necessity, our tests and documentation will also be expanded to reflect the variable behaviour of the "git lfs pull" command in particular, since its effects in a bare repository depend in part on the installed version of Git. Before we make these changes, we first revise our existing tests of the "git lfs checkout" and "git lfs pull" commands with partial clones and sparse checkouts so that the tests confirm the key differences in behaviour when the installed version of Git is v2.42.0 or higher. Our tests now demonstrate that with an older version of Git, objects will be fetched (in the case of the "git lfs pull" command) and checked out for all Git LFS files, including those outside the configured sparse cone. We also update the manual pages for these commands to include an explanation of how their operation varies depending on the installed version of Git, how this may affect repositories with partial clones and sparse checkouts, and the options available to users if they find the "git lfs checkout" and "git lfs pull" commands appear to be ignoring certain files. As well, we edit the initial section in our git-lfs-pull(1) manual page where we incorrectly state that the command is always equivalent to running "git lfs fetch" followed by "git lfs checkout", and fix the formatting of the example commands provided in this section. When we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR #5054, the two example commands in this section were accidentally merged onto a single line, and the "<remote>" option for the "git lfs fetch" command was elided. We therefore restore the original version of these two example commands and add leading shell prompt indicators to further clarify that the example includes two separate commands.
hswong3i
pushed a commit
to alvistack/git-lfs-git-lfs
that referenced
this pull request
Oct 18, 2025
In commit 5aa7be5 of PR git-lfs#5796 we added tests of the sparse checkout support provided by our "git lfs checkout" and "git lfs pull" commands, which makes use of the "git ls-files" command and the --sparse option that was introduced for that command in Git v2.35.0. In practice, the "git lfs checkout" and "git lfs pull" commands require Git v2.42.0 or higher to be available before they invoke "git ls-files", and otherwise fall back to using the "git ls-tree" command. We require at least Git v2.42.0 because that version introduced support for the "objecttype" field name in the "git ls-files" command's --format option and we depend on that field to be able to mimic the output format of the "git ls-tree" command with the "git ls-files" command. We noted these details in commit beae114 of PR git-lfs#5699, when we revised the runScanLFSFiles() function in our "lfs" package to choose between the use of "git ls-files" and "git ls-tree". One difference between the "git ls-files" and "git ls-tree" commands, however, is that the former lists the files in the Git index (since we always pass the --cached option) while the latter lists the files in the Git tree associated with a given reference, which in the case of our "git lfs checkout" and "git lfs pull" commands is always the current "HEAD" symbolic reference. As a consequence, as discussed in issue git-lfs#6004, if certain files are absent from the current working tree and Git index as the result of a partial clone or sparse checkout, the behaviour of the "git lfs checkout" and "git lfs pull" commands varies depending on the installed version of Git. If Git v2.42.0 or higher is installed, the "git lfs checkout" and "git lfs pull" commands invoke the "git ls-files" command and provide an "attr:filter=lfs" pathspec so the Git command will filter out files which do not match a Git LFS filter attribute. However, in order to be reported, Git LFS pointer files must exist in the Git index; if they only appear in the working tree or the Git tree associated with the "HEAD" reference, they will be ignored. (Note that in a non-bare repository, the "git ls-files" command will only match the "attr:filter=lfs" pathspec against attributes defined in ".gitattributes" files in the index or working tree, plus any local files such as the "$GIT_DIR/info/attributes" file. Any ".gitattributes" files that are present only in the Git tree associated with the "HEAD" reference will not be consulted. In a bare repository, meanwhile, the "git ls-files" command will by default not match the pathspec against attributes defined in ".gitattributes" files at all, regardless of whether such files exist in the index or in the tree referenced by "HEAD".) If a version of Git older than v2.42.0 is installed and so the "git ls-tree" command is invoked instead of the "git ls-files" command, then a full list of the files in the tree-ish referenced by "HEAD" is returned. The "git lfs checkout" and "git lfs pull" commands will then attempt to check out the Git LFS objects associated with all the Git LFS pointer files found in this list. In the case of the "git lfs pull" command, it will also try to fetch those objects if they are not already present in the local storage directories. (Note, though, that when the "git lfs checkout" and "git lfs pull" commands retrieve a list of files using the "git ls-tree" command, they do not check whether the pointer files they find in that list actually match Git LFS filter attributes in any ".gitattributes" or other Git attributes files. So a user may remove all the ".gitattributes" files from their working tree and index, commit those changes to "HEAD", and the Git LFS commands will still attempt to check out objects for any files found in the "HEAD" commit's tree that can be parsed as valid pointers. When the "git ls-files" command is used instead of the "git ls-tree" command to retrieve a file list, this legacy behaviour does not occur, because the "attr:filter=lfs" pathspec requires that the "git ls-files" command only return a list of files which match at least one Git LFS filter attribute.) In subsequent commits we will alter how the "git lfs checkout" and "git lfs pull" commands operate within bare repositories and how they handle file paths, including by changing the current working directory to the root of the current working tree, if one is present. Of necessity, our tests and documentation will also be expanded to reflect the variable behaviour of the "git lfs pull" command in particular, since its effects in a bare repository depend in part on the installed version of Git. Before we make these changes, we first revise our existing tests of the "git lfs checkout" and "git lfs pull" commands with partial clones and sparse checkouts so that the tests confirm the key differences in behaviour when the installed version of Git is v2.42.0 or higher. Our tests now demonstrate that with an older version of Git, objects will be fetched (in the case of the "git lfs pull" command) and checked out for all Git LFS files, including those outside the configured sparse cone. We also update the manual pages for these commands to include an explanation of how their operation varies depending on the installed version of Git, how this may affect repositories with partial clones and sparse checkouts, and the options available to users if they find the "git lfs checkout" and "git lfs pull" commands appear to be ignoring certain files. As well, we edit the initial section in our git-lfs-pull(1) manual page where we incorrectly state that the command is always equivalent to running "git lfs fetch" followed by "git lfs checkout", and fix the formatting of the example commands provided in this section. When we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, the two example commands in this section were accidentally merged onto a single line, and the "<remote>" option for the "git lfs fetch" command was elided. We therefore restore the original version of these two example commands and add leading shell prompt indicators to further clarify that the example includes two separate commands.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In commit 8945cbf of PR git-lfs#5054 we ceased using the "ronn" Ruby gem to generate our manual pages from their source files, and so the RONN* variables in our Makefile are no longer used and can now be removed.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page. We now restore another missing term, this time in the description section of the git-lfs-checkout(1) manual page, where the "<glob-pattern>" term was accidentally removed. We also take the opportunity to rephrase the sentence containing this term slightly so as to avoid the use of a trailing plural "s" character, as that causes formatting errors when rendering the AsciiDoc source into HTML or roff.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page, and in a prior commit in this PR we restored another in the git-lfs-checkout(1) manual page. We now restore another missing term, this time in the git-lfs-config(5) manual page, in the entry for the "lfs.customtransfer.<name>.path" configuration option, where the "<name>" term was accidentally removed from a sentence in which it was the first word. We also take the opportunity to add a leading definite article to the sentence so to make it slightly more idiomatic and readable.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
When we converted our manual page source files from the Ronn format to the AsciiDoc format in commit 0c66dcf of PR git-lfs#5054, a few terms were accidentally dropped if they were delimited with angle brackets but not also enclosed with backtick characters. In commit 219518e of PR git-lfs#5414 we restored one such missing term in the git-lfs-logs(1) manual page, and in prior commits in this PR we restored several others in the git-lfs-checkout(1) and git-lfs-config(5) manual pages. We now restore another missing term, this time in the description section of the git-lfs-smudge(1) manual page, where the "<path>" term was removed from the sentence which explained the purpose of the "git lfs smudge" command's optional progress log file path argument.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-migrate(1) manual page, the description text of the entry for the --skip-fetch option to the "git lfs migrate" command was fully indented except for the final line, likely because it begins with a monospace delimiter, so we adjust that now. Similarly, the second line of the description of the --theirs option in the git-lfs-checkout(1) manual page is not indented to match the first line, so we add the indentation now.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In our git-lfs-prune(1) manual page we dedicate one section to a explanation of how the Git LFS client determines whether an object is sufficiently "recent" to be retained and not pruned. In this section we list the Git configuration options that control the expiry and retention periods for objects, including settings such as "lfs.fetchRecentCommitsDays", "lfs.fetchRecentRefsDays", and "lfs.pruneOffsetDays". The list contains two entries, one for the "lfs.pruneOffsetDays" option and one for three of the "lfs.fetchRecent*" options. When the git-lfs-prune(1) manual page was first added in commit bd72983 of PR git-lfs#742, this list of the Git configuration options was formatted such that each entry began with the option name or names as headers on separate lines, followed by a description of their effects as a separate paragraph. When we converted our manual pages from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, the list was formatted as an unordered list where the option name or names and the subsequent description were simply all placed together as a single paragraph. To help make this section of the git-lfs-prune(1) manual page slightly more readable, we adjust its formatting now to use an AsciiDoc description list rather than an unordered list. By doing so, we can restore the option names as distinct headers, each of which will appear on a separate line when we render the source file into HTML or roff with Asciidoctor. The description text of each entry will also then be rendered as an indented paragraph following the entry's headers.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In our git-lfs-migrate(1) manual page, one of the entries in the list of options supported by the "git lfs migrate info" subcommand describes the --unit option, and enumerates the set of storage capacity units that we accept for that option. In this option's entry we provide two lists, one of decimal SI units (e.g., kb, MB) and one of binary IEC units (e.g., KiB, MiB), with the intent that they should each form a single entry in a second-level list nested within the top-level list of command options. However, when we converted our manual page source files from the Ronn format to AsciiDoc in commit 0c66dcf of PR git-lfs#5054, this second-level list was flattened into continuous text, so we restore it now. In this commit we simply match the formatting already in use in several second-level lists in the git-lfs-config(5) manual page, although it does not render properly in any of our output formats. We anticipate that in a subsequent PR we will adjust the formatting of all of these second-level lists so they render correctly when converted to HTML and roff by Asciidoctor.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-logs(1) and git-lfs-pre-push(1) manual pages, though, the list of options were accidentally left formatted as unordered lists rather than description lists, so we revise them now to match the description list format we use in the manual pages for our other commands.
chrisd8088
added a commit
to chrisd8088/git-lfs
that referenced
this pull request
Nov 6, 2025
In commit f9fd1af of PR git-lfs#5054 we corrected the indentation in some of our manual page source files, following their conversion to the AsciiDoc format in commit 0c66dcf in the same PR. For a number of pages these corrections entailed reformatting the lists of options supported by the different commands into description lists, where each entry consists of one or more terms, followed by a double-colon delimiter, followed by a description of the term or terms. In the case of the git-lfs-track(1) manual page, though, the second colon character was accidentally omitted from the term of the final entry in the list of command options. Specifically, because the entry for the --no-modify-attrs option lacks a full term delimiter, it does not render properly when converted to HTML or groff, so we correct this problem now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
For various reasons, we'd like to switch to AsciiDoc for our documentation. Port all of the docs over from ronn, at first using a basic automated conversion, and then fix up individual problems.
Fixes #4897