./bitcoin.conf file should not cause confusion with ./datadir/bitcoin.conf #29139

Is there an existing issue for this?

• I have searched the existing issues

Current behaviour

There is the bitcoin.conf file in the bitcoin-26.0 directory. It's not obvious that the configuration from the file is not used by Bitcoin Core.

Severity: minor (cosmetic issue).

Expected behaviour

There isn't the same filename (bitcoin.conf) used for the description (./bitcoin.conf) and actual configuration (./datadir/bitcoin.conf). There could be the ./example-bitcoin.conf instead.

Steps to reproduce

Extract archive/install Bitcoin Core 26.0.

Relevant log output

No response

How did you obtain Bitcoin Core

Pre-built binaries

What version of Bitcoin Core are you using?

26.0

Operating system and version

Windows

Machine specifications

No response

Are you referring to the file https://github.com/bitcoin/bitcoin/blob/26.x/share/examples/bitcoin.conf ?

Which includes the preface:

## All possible configuration options are provided. To use, copy this file
## to your data directory (default or specified by -datadir), uncomment
## options you would like to change, and save the file.

bitcoin.conf usage is also covered in https://github.com/bitcoin/bitcoin/blob/master/doc/bitcoin-conf.md and again in https://github.com/bitcoin/bitcoin/blob/master/doc/files.md

What could we do to mitigate the confusion you are reporting?

Yes, the exact prefix in the file is:

##
## bitcoin.conf configuration file.
## Generated by contrib/devtools/gen-bitcoin-conf.sh.
##
## Lines beginning with # are comments.
## All possible configuration options are provided. To use, copy this file
## to your data directory (default or specified by -datadir), uncomment
## options you would like to change, and save the file.
##

I would suggest renaming the file, e.g. "example-bitcoin.conf".

Ok I don't agree that that would be an improvement, because:

1. The path already contains the word "example" (examples/bitcoin.conf)
2. Changing that file's name would also require an additional comment in the header instructing the user to rename the file as well as copy it to their data directory
3. The default datadir for all platforms is very clear in several places in the docs, and that default datadir is never inside the code repository

1. The path already contains the word "example" (examples/bitcoin.conf)

It is not true. The path doesn't contain the word "example", see: https://bitcoincore.org/bin/bitcoin-core-26.0/bitcoin-26.0-win64.zip.

Aha ok sorry I misunderstood, you were referring to the release packages not the source code repo. Still I think the instructions in the header are clear. However it does seem reasonable to include a README file in the release packages with at least some minimal explanation of the contents of the package, inclusing how to use the example conf file and also identifying what the executables are inbin/.

Ok I don't agree that that would be an improvement, because:

2. Changing that file's name would also require an additional comment in the header instructing the user to rename the file as well as copy it to their data directory

I agree with this point. No need to force the average-skilled user to perform an extra action.

Perhaps the best solution is simply to move the example conf back inside share/examples/bitcoin.conf in the release tar, as we have it here in the repo? That way if people unzip-to-dir which I assume is how it's usually done?, the example conf also won't be floating loosely inside /usr/local:

# Check contents
tar -tzvf bitcoin-26.0-x86_64-linux-gnu.tar.gz
# Unzip directly to /usr/local
sudo tar -xzvf bitcoin-26.0-x86_64-linux-gnu.tar.gz -C /usr/local/

IMO folks looking for an example conf would also be more likely to look for and find it in share/.

IMO folks looking for an example conf would also be more likely to look for and find it in share/.

agreed. im testing your commit in a guix build locally, will ack that PR

After catching up on the discussion in #29903 my opinion now is that we close this issue and the pull request. The bitcoin.conf file is self-documented and the datadir location where it belongs is also well documented. If users are opening that file to change settings but ignoring the first line in that file that tells them how to use it, I'm not sure there's anything else the developers can do.

I'd recommend adding a README file in the tar but that probably won't prevent this user behavior either.

I agree, going to close this issue and #29903 for now