Parse version from changelog

[CatsDeservePets]

• Fixes: Make -version flag work for unreleased versions #2234

This PR improves version information for unreleased versions.
It achieves this by embedding and parsing CHANGELOG.md.

Before:

lf -version
Built at commit: a2987b42c6c26787ef033cf53a0bdbeed6177d0a 2025-11-07T03:47:28Z
Go version: go1.25.3

After:

lf -version
r39 (Unreleased)
Built at commit: a2987b42c6c26787ef033cf53a0bdbeed6177d0a 2025-11-07T03:47:28Z
Go version: go1.25.3

It also exposes the changelog as news which makes it possible to create a neovim-inspired command to show the latest changes:

cmd news $lf -remote "query $id news" | $PAGER

[CatsDeservePets]

Hello @joelim-work,
any thoughts on this?

I was wondering whether I should introduce a completely new /gen/log.sh. As of right now, running /gen/doc.sh always updates lf even though the date is the only thing changing. Of course, we could also introduce some smarter logic here that uses git dates or diffs or something like that. I am undecided which route we should take here.

[joelim-work]

The date simply comes from doc.sh and is set to the current date:

lf/gen/doc.sh

Line 21 in b653506

[ -z "${date:-}" ] && date=$(date +%F)

The reason for this was so that every time a new release was made, the documentation would be generated, and the date shown in the man page would match the release date. I am not sure how useful this actually is in practice though, since I don't look at the date myself.

I'm also a bit unsure about naming the script doc.sh if it is also being used to generate news. Maybe it is better to place it in a new script, but the downside is that it is less convenient and it might be possible to run one script but forget to run the other. Either way is fine for me though.

[CatsDeservePets]

The date simply comes from doc.sh and is set to the current date:

lf/gen/doc.sh

Line 21 in b653506

[ -z "${date:-}" ] && date=$(date +%F)

The reason for this was so that every time a new release was made, the documentation would be generated, and the date shown in the man page would match the release date. I am not sure how useful this actually is in practice though, since I don't look at the date myself.

I'm also a bit unsure about naming the script doc.sh if it is also being used to generate news. Maybe it is better to place it in a new script, but the downside is that it is less convenient and it might be possible to run one script but forget to run the other. Either way is fine for me though.

How about this? Asking the user what to do using an interactive menu (quick and dirty implementation)?

[joelim-work]

The point I was trying to make above is that the script was originally used for generating documentation only, which is why it was called doc.sh. Now that you are changing it to generate news as well, the name could be changed to something more generic (e.g .pandoc.sh, but other names are acceptable).

I don't think user input is necessary, the script should simply generate everything. If there are no changes to the source Markdown files then the result should be a no-op. The only edge case is the date that is displayed in the man page, which is set to the date that the script is run. IMO the date is not that important compared to the version of lf and can be dropped if it causes issues.

I'm also not a fan of using different mechanisms for handling :help (via lf -doc) and :news (via query commands), given that they do the same thing but with different contents. I am leaning towards the lf -doc implementation since query commands are for requesting information about specific instances, and also the protocol (using a blank line as the terminator) was designed for returning actual data.

---

Now going back to the original issue #2234, it looks like you just want to be able to distinguish between release builds and custom builds. But this can be solved just by modifying build.sh to use git describe --tags, which shows either just the tag (e.g. r38) when building off a release tag, or additional information (e.g. r38-72-gc320102) if making a custom build.

At this point I'm not sure which issue you're trying to solve, is it to improve the --version flag parsing (which probably doesn't need to be coupled to the changelog), or making the changelog viewable (could this be implemented externally via user configuration?).

[joelim-work]

Sorry, I didn't mean to close the PR, was an accidental mouse slip from me.

[CatsDeservePets]

The point I was trying to make above is that the script was originally used for generating documentation only, which is why it was called doc.sh. Now that you are changing it to generate news as well, the name could be changed to something more generic (e.g .pandoc.sh, but other names are acceptable).

I don't think user input is necessary, the script should simply generate everything. If there are no changes to the source Markdown files then the result should be a no-op. The only edge case is the date that is displayed in the man page, which is set to the date that the script is run. IMO the date is not that important compared to the version of lf and can be dropped if it causes issues

Alright, got it.

I'm also not a fan of using different mechanisms for handling :help (via lf -doc) and :news (via query commands), given that they do the same thing but with different contents. I am leaning towards the lf -doc implementation since query commands are for requesting information about specific instances, and also the protocol (using a blank line as the terminator) was designed for returning actual data.

I thought of this as well. I did not do it as introducing a -news or -changelog flag seemed rather unconventional to me (I am not aware of tools doing this). I do agree, this would simplify the code though.

Now going back to the original issue #2234, it looks like you just want to be able to distinguish between release builds and custom builds. But this can be solved just by modifying build.sh to use git describe --tags, which shows either just the tag (e.g. r38) when building off a release tag, or additional information (e.g. r38-72-gc320102) if making a custom build.

This is debatable, however I'd rather have lf show r39 (i.e. the next version) instead of r38xxx as this reflects the version number a feature actually gets implemented.
My initial use-case is being able to use my normal lfrc file to set options which aren't released yet. Therefore, having the version reflect the next full version makes this much simpler.

At this point I'm not sure which issue you're trying to solve, is it to improve the --version flag parsing (which probably doesn't need to be coupled to the changelog),

Embedding CHANGELOG.md and using it to parse the version was a suggestion made by @Limero in #2234 (comment). You gave it a thumbs up so I thought this is the way to go.

or making the changelog viewable (could this be implemented externally via user configuration?).

Making the changelog viewable is a nice side-effect of solving the version parsing this way. This is already possible, however not really convenient. I did this by looking for CHANGELOG.md inside dirname of the current executable. If not found, in its parent dir (necessary when using the version installed via homebrew instead of an executable inside a local repo of mine).

[joelim-work]

I thought of this as well. I did not do it as introducing a -news or -changelog flag seemed rather unconventional to me (I am not aware of tools doing this). I do agree, this would simplify the code though.

I also haven't seen any tools that provide a -news or -changelog option either. However, AFAIK most tools don't provide built-in functionality for viewing the changelog, and if there is a changelog then it is made available externally (e.g. website). Even Neovim, which provides a :help news command, bundles the changelog as a separate file instead of embedding it directly inside the application. So this suggests to me that the idea of including such functionality in a tool is what is "unconventional" here, rather than the names of the command line options.

This is debatable, however I'd rather have lf show r39 (i.e. the next version) instead of r38xxx as this reflects the version number a feature actually gets implemented.
My initial use-case is being able to use my normal lfrc file to set options which aren't released yet. Therefore, having the version reflect the next full version makes this much simpler.

I understand that you are trying to compare versions in order to dynamically enable certain options that may or may not be available. But using a future version that is unreleased (r39 in this case) can be misleading since that version doesn't actually exist yet, whereas a version string like r38-74-g6e804b1 indicates that it is 74 commits ahead of the existing version r38.

Bumping to the next unreleased version is also not reliable for checking if a feature exists or not. Consider the following hypothetical git history:

5aeb9a4 Add feature2
9e5f6af Add feature1
49f2a7c (tag: r38) Prepare for r38 release (#2163)

If the version string is set to r39 (Unreleased) for any commit after r38, given that the version string is the same for these commits, how do you distinguish between commits before and after a new feature is actually implemented? You might checkout the commit where feature1 is added, and the config file could end up referencing feature2 because the version string says r39 (Unreleased), even though feature2 doesn't actually exist in that commit. So when building at any arbitrary commit, I'm not sure if there is a way to detect whether a feature exists other than trying to configure it.

If you just wanted to hide errors for possibly non-existent features, I guess another idea is to just clear them using echo:

# unreleased features
set feature1 true
set feature2 true
echo

# everything else
set drawbox
set hidden

Embedding CHANGELOG.md and using it to parse the version was a suggestion made by @Limero in #2234 (comment). You gave it a thumbs up so I thought this is the way to go.

I must admit that I do sometimes change my mind and go back on what I might have said previously. The reason for this is simply because I will not know everything about a problem before having to think of a solution, and sometimes what I learn about the problem later on affects my judgment. For this particular case, it is definitely possible to embed the contents of the changelog into the application and reference it when printing the version - anything can be implemented if the code is written for it. But the question is, does such a design make sense? Now the changelog is coupled directly to the implementation of the -version flag, when it was originally intended to be a document read by users, and TBH I haven't seen any other program do something like this.