The new code in the pull request automatically preserves comment lines in the /etc/config/* config files, also if changes are made through luci.
Since April 19 2026, the pull request is ready to be reviewed and merged.
I don't want to seem impatient. I know everyone is busy, especially with the flood of bug reports coming out of the AI tooling. I just want to be sure someone will notice it eventually because there's not a lot of activity for uci.
How do I get eyes on this? Should I just wait, or can I contact someone?
This comes up from time to time and does sound like a good idea... but
I'm not sure uci always works in the way you think it does.
The comments are only stripped out on a uci commit - this is the only time the config file is written to (Luci works a bit differently but same principle).
But the order of the individual lines can change so comments on a line of their own will become misplaced and there is no mechanism for linking such lines with the option being configured.
What happens if you want to use uci to add, delete or change a comment?
Will you have to edit the actual config file?
What if you edit the config file when there are uncommitted changes?
This will break how uci is supposed to work.
A reliable way to include comments is to embed them as list entries.
As an example, I quickly added some comments to my test router:
root@meshnode-8ec9:~# uci add_list system.ntp.comment='enable_server does what it says. You can use the enabled server from your computer to get the time'
root@meshnode-8ec9:~# uci add_list system.ntp.comment='server 0 sometimes gets quite busy'
root@meshnode-8ec9:~# uci export system
package system
config system
option hostname 'meshnode-8ec9'
option timezone 'GMT0'
option zonename 'UTC'
option ttylogin '0'
option log_size '128'
option urandom_seed '0'
config timeserver 'ntp'
option enabled '1'
option enable_server '0'
list server '0.openwrt.pool.ntp.org'
list server '1.openwrt.pool.ntp.org'
list server '2.openwrt.pool.ntp.org'
list server '3.openwrt.pool.ntp.org'
list comment 'enable_server does what it says. You can use the enabled server from your computer to get the time'
list comment 'server 0 sometimes gets quite busy'
root@meshnode-8ec9:~#
If worded sensibly, any changes in order within the section will not matter so much.
Note I left the uci changes uncommitted in this instance ( there are already uncommitted changes present).
Here is the actual config file:
root@meshnode-8ec9:~# cat /etc/config/system
config system
option hostname 'OpenWrt'
option timezone 'GMT0'
option zonename 'UTC'
option ttylogin '0'
option log_size '128'
option urandom_seed '0'
config timeserver 'ntp'
option enabled '1'
option enable_server '0'
list server '0.openwrt.pool.ntp.org'
list server '1.openwrt.pool.ntp.org'
list server '2.openwrt.pool.ntp.org'
list server '3.openwrt.pool.ntp.org'
root@meshnode-8ec9:~#
No, list comment is not reserved, you can use any valid uci keyword that the package itself does not use.
This will be section dependent and can appear in multiple sections.
All in all, "list comment" is pretty safe to use.
root@meshnode-8ec9:~#
root@meshnode-8ec9:~# uci add_list system.@system[0].comment='log_size sets the size of the log before it auto-rotates'
root@meshnode-8ec9:~#
root@meshnode-8ec9:~# uci export system
package system
config system
option hostname 'meshnode-8ec9'
option timezone 'GMT0'
option zonename 'UTC'
option ttylogin '0'
option log_size '128'
option urandom_seed '0'
list comment 'log_size sets the size of the log before it auto-rotates'
config timeserver 'ntp'
option enabled '1'
option enable_server '0'
list server '0.openwrt.pool.ntp.org'
list server '1.openwrt.pool.ntp.org'
list server '2.openwrt.pool.ntp.org'
list server '3.openwrt.pool.ntp.org'
list comment 'enable_server does what it says. You can use the enabled server from your computer to get the time'
list comment 'server 0 sometimes gets quite busy'
root@meshnode-8ec9:~#
With the code in the pull request, comments are associated with a config, option or list keyword, so they stay in place.
E.g.
# comment line before and associated with config timeserver 'ntp'
# comment line 2 before and associated with config timeserver 'ntp'
config timeserver 'ntp' # comment after and associated with config timeserver 'ntp'
# comment line 1 before and associated with option enabled
# comment line 2 before and associated with option enabled
option enabled '1' # comment after and associated with option enabled
The syntax allows comments, so uci and libuci should not delete them.
Also, you want to be able to comment a specific option with the option, not somewhere else that's reordered randomly.
Not necessarily. This example is trivial, but the following can happen:
root@meshnode-8ec9:~# uci del system.ntp.enabled
root@meshnode-8ec9:~# uci set system.ntp.enabled='0'
root@meshnode-8ec9:~# uci export system
package system
config system
option hostname 'meshnode-8ec9'
option timezone 'GMT0'
option zonename 'UTC'
option ttylogin '0'
option log_size '128'
option urandom_seed '0'
list comment 'log_size sets the size of the log before it auto-rotates'
config timeserver 'ntp'
option enable_server '0'
list server '0.openwrt.pool.ntp.org'
list server '1.openwrt.pool.ntp.org'
list server '2.openwrt.pool.ntp.org'
list server '3.openwrt.pool.ntp.org'
list comment 'enable_server does what it says. You can use the enabled server from your computer to get the time'
list comment 'server 0 sometimes gets quite busy'
option enabled '0'
root@meshnode-8ec9:~#
Comments are not associated with anything from the point of view of uci.
That's possible, yes, but a different problem that can be addressed in the code that uses uci. I've installed the changes on my system and changed settings with LuCI, and the comments of all config, option and list keywords not touched by the LuCI changes were preserved.
Currently the new code does not automatically preserve the comment of a changed option because the comment may be outdated. If LuCI allows to add/edit comments, LuCI can preserve the comment with the option. The new code provides a command line interface to retrieve the comment and set a comment with the option value. This can be extended for LuCI, and LuCI can be extended to allow to edit a comment with every section and option. Which I'm prepared to contribute to.
My point is that there is nothing that connects comment lines with options, lists or even sections.
Here is a snippet of the installed default config file for a package:
# debuglevel
# Set Debug Level (0-3)
# Default: 1
# 0 : Silent (only initial startup, LOG_ERR, LOG_EMERG and LOG_CRIT messages will be seen, otherwise there will be no logging.)
# 1 : LOG_ERR, LOG_EMERG, LOG_CRIT, LOG_WARNING and LOG_NOTICE. (Level 1 is the default level.)
# 2 : debuglevel 1 + LOG_INFO
# 3 : debuglevel 2 + LOG_DEBUG
#option debuglevel '2'
###########################################################################################
Here, everything is a comment.
If the debuglevel is changed from the default using uci and if uci preserved comments, the newly set option debuglevel would appear at the end of a very long config file, completely unlinked.
There is a reason why uci removes comments on a commit.
Yes it could conserve them, but then things could very rapidly get out of hand.
if you need to make or retain config comments for some reason, then there is surely a more efficient, less evasive solution then what has been proposed...
first thought, store them someplace safe (possibly make them available to sysupgrade)
some.config --> some.comments or some.config.notes ... you get the picture
In general, what is best for many out weighs what best for one .. two.
My suggestion, spend some time to create a solution that works for you and doesn't effect anyone/everyone else. If it works good and you think it may be used by others ... then make it a package and maintain it.
In your example, the comment lines for the option are also before the option line itself. This is the convention.
A comment at the end of the line of the option itself is also considered to be for that option, this is also the convention.
That is exactly what the new code implements.
For your specific example, there is only a comment, and no config, option, or list keyword that the comment is associated with. The new code does not preserve a comment that is not associated with anything (basically, a comment at the end of the file), so the comment in your example would not be preserved.
So, the new code does exactly what you desire in this case. uci preserves the order of config sections and options. These are stored in a list. Nothing will be reordered or 'get out of hand'.
remove all test from the pr and provide them, or link to them, in discussion. Only actual code changes should be included in the pr ... +/-8 files changed compared to 68 may possibly get someone to look at it.
I do find it very ironic that a massive commit for persevering comments, contains little to no comments of the proposed changes, perhaps of few may actually be warranted here ..no ?
The biggest hurdle, as i see it, is making your case for such an invasive commit for preserving and or adding comments to a config file. You can fetch original comments from rom if there is ever such a need ... or as i already suggested, better ways to document/comment code ...
UCI has been effective for eons without retaining comments. Somehow users have found a way to either do without them, or do it without a major addition to the rock solid code-base.
I do appreciate the amount of work you put into it. but why not just use it yourself ?? ... start a gh repo so others may use and test it as well. But why should all users, with little to no interest in such a feature in the first place, be forced force to add it to an already bloated code-base ...
My opinion is that this feature should not be present and the PR should not be merged as it is added without full consideration of how uci really functions.
There is no such convention. The only convention is for uci to ignore # comments.
Then it is very possible it might break something as proper use of the uci command has not been considered.
I gave two examples. The latter was an example of a very common "default install" config file snippet.
Every line in the snippet was commented out with the usual # symbol.
This example shows that if the option referred to in the comments was added using a uci set command (as it should be done), the option will be added to the end of the section in the config file.
The former example was a "real world" implementation of section specific comments within the full context of the uci system which is deeply tied into how packages and services are started and run.
How is your code associating a comment with an option? I don't see that anywhere.
Do you keep some separate database of which comments are associated with which # comment line? I don't think so.
Your code will have to move # comments around the /etc/config/ file to follow any movements of option or list lines.
No that is what YOUR code seems to do.
It absolutely does not.
This is the strongest piece of evidence that you do not have a full grasp of how uci works.
I even gave examples showing it was not the case.
Perhaps you have come from the school of thought that config files are always edited.
Whereas uci is designed to update configs dynamically and rewrite the physical /etc/config file on request.
There is a big difference.
Editing directly is ok when first setting up as it (usually) gives the same result as uci commands, but has the potential dangers of:
Messing up the file
Conflicting with the file's package, particularly if it is a service daemon.
So, strictly speaking uci should be the preferred method of changing config files.
Yes and yes.
The syntax ignores them.
After changes are made by uci, to make those changes survive a reboot, a uci commit is called.
This re-writes the entire config file, without, of course, the # comments it ignored when initially reading the file.
My suggested solution is to add a section specific list entry. If committed this will be preserved until a uci del_list and subsequent commit have been executed.
This is non-invasive and requires no code changes. Just use it like in my example.