docs: Add doc/bitcoin-conf.md #14497

pull hebasto wants to merge 1 commits into bitcoin:master from hebasto:20181016-bitcoin-conf-md changing 2 files +38 −0

hebasto commented at 9:18 PM on October 16, 2018: member
From the IRC:

2018-10-16T05:35:03 <wumpus> if something can be solved by better documentation, please work on documentation! 2018-10-16T05:35:12 <wumpus> don't change the code instead

Refs:
- #14370
- #14427
- #14494
Based on the BITCOIN.CONF(5) manual page written by Micah Anderson <micah@debian.org> for the Debian system.
ryanofsky approved
ryanofsky commented at 9:43 PM on October 16, 2018: member

utACK c25f444785ccf94b6c648ac65d919f759189516e. This seems well written and pretty comprehensive. It might be nice if in the future we could also make this a bitcoin.conf manpage.

in doc/bitcoin-conf.md:5 in c25f444785 outdated

   0 | @@ -0,0 +1,11 @@
   1 | +# `bitcoin.conf` - Bitcoin configuration file
   2 | +
   3 | +All command-line options (except for `-conf`) may be specified in a configuration file, and all configuration file options (except for `-includeconf`) may also be specified on the command line. Command-line options override values set in the configuration file and configuration file options override values set in the GUI.
   4 | +
   5 | +The configuration file is a plain text file and consist of 'setting=value' entries, one per line. Leading and trailing whitespaces are removed. A number sign (`#`) indicates a comment. Comments and empty lines are ignored.

practicalswift commented at 10:15 PM on October 16, 2018:

Use back-ticks also for setting=value to make it consistent?

laanwj commented at 2:09 PM on October 17, 2018:

maybe "(#) indicates the start a comment, and will make the parser ignore until the end of the line"

promag commented at 3:07 PM on October 17, 2018:

Could mention that, although possible, it's not recommended to have a setting and a comment in the same line?

foo=bar # reasons

# reasons
foo=bar

flack commented at 4:51 PM on October 18, 2018:

The configuration file is a plain text file and consists of 'setting=value' entries, one per line. Leading and trailing whitespaces are removed. A number sign (`#`) indicates a comment. Comments and empty lines are ignored.

practicalswift commented at 10:15 PM on October 16, 2018: contributor

utACK c25f444785ccf94b6c648ac65d919f759189516e

Very nicely written!

in doc/bitcoin-conf.md:3 in c25f444785 outdated

   0 | @@ -0,0 +1,11 @@
   1 | +# `bitcoin.conf` - Bitcoin configuration file
   2 | +
   3 | +All command-line options (except for `-conf`) may be specified in a configuration file, and all configuration file options (except for `-includeconf`) may also be specified on the command line. Command-line options override values set in the configuration file and configuration file options override values set in the GUI.

jimmysong commented at 11:52 PM on October 16, 2018:

Perhaps mention that certain values need specifying like testnet=1 in the configuration, but is just -testnet on command-line?

laanwj commented at 2:15 PM on October 17, 2018:

and even less intuitive: this is true for negated boolean options too, so -noconnect becomes noconnect=1, see #14152

jimmysong commented at 11:53 PM on October 16, 2018: contributor

Great initiative! I'd love to see a commented example as a way to describe what some options do.
fanquake added the label Docs on Oct 17, 2018

in doc/bitcoin-conf.md:11 in c25f444785 outdated

   6 | +
   7 | +The configuration file is not automatically created; you can create it using your favorite plain-text editor. By default, the configuration file name is `bitcoin.conf` and it is located in the Bitcoin data directory, but both the Bitcoin data directory and the configuration file path may be changed using the `-datadir` and `-conf` command-line arguments.
   8 | +
   9 | +The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files.
  10 | +
  11 | +Network specific options can be placed into the sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) and `[regtest]`.

sipa commented at 7:09 AM on October 17, 2018:

I believe you can also write network specific options by prefixing the option with netname..

laanwj commented at 2:11 PM on October 17, 2018:

yes, though I think in general when writing user documentation, documenting one way that works (and is recommended) is good enough; the conversion to a.b might be seen as an implementation detail that will just confuse

but don't care strongly, could add it as extra information

flack commented at 4:53 PM on October 18, 2018:

Network specific options can be placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`.

laanwj commented at 2:04 PM on October 17, 2018: member

thanks a lot for writing documentation!

It might be nice if in the future we could also make this a bitcoin.conf manpage.

it's possible to generate a manual page from .md, AFAIK, though that's something for the future
in doc/bitcoin-conf.md:1 in c25f444785 outdated
```
   0 | @@ -0,0 +1,11 @@
   1 | +# `bitcoin.conf` - Bitcoin configuration file
```
promag commented at 3:08 PM on October 17, 2018:

Drop Bitcoin?
promag commented at 3:09 PM on October 17, 2018: member

ACK.

Could mention that this configuration is used by bitcoind, bitcoin-qt and bitcoin-cli?
hebasto force-pushed on Oct 18, 2018
hebasto commented at 9:04 PM on October 18, 2018: member

All comments are addressed. Please re-review.
promag commented at 9:19 PM on October 18, 2018: member

This is based on https://manpages.debian.org/unstable/bitcoind/bitcoin.conf.5.en.html, should give credit?

in doc/bitcoin-conf.md:35 in 36efaf667f outdated

  30 | +- placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`;
  31 | +- prefixed with a chain name; e.g., `regtest.maxmempool=100`.
  32 | +
  33 | +## Configuration File Path
  34 | +
  35 | +The configuration file is not automatically created; you can create it using your favorite plain-text editor. By default, the configuration file name is `bitcoin.conf` and it is located in the Bitcoin data directory, but both the Bitcoin data directory and the configuration file path may be changed using the `-datadir` and `-conf` command-line options.

flack commented at 9:46 PM on October 18, 2018:

Nit: above you write "plain text" as two words, here you write it hyphenated. Not sure which version is better, but it would probably be good to be consistent

hebasto commented at 9:54 PM on October 18, 2018: member

@promag

This is based on https://manpages.debian.org/unstable/bitcoind/bitcoin.conf.5.en.html, should give credit?

How?
promag commented at 9:59 PM on October 18, 2018: member

@hebasto not sure, maybe in the PR description which will be in the merge commit?
hebasto commented at 10:06 PM on October 18, 2018: member

@promag The PR description has been updated.
Add `doc/bitcoin-conf.md` 1fb3c167c3
hebasto force-pushed on Oct 18, 2018
hebasto commented at 10:15 PM on October 18, 2018: member

@flack Fixed.
sipa commented at 2:07 AM on October 20, 2018: member

utACK 1fb3c167c3cbd4a432a064b299439b3430157dda
MarcoFalke commented at 6:28 AM on October 20, 2018: member

ACK 1fb3c167c3cbd4a432a064b299439b3430157dda
fanquake renamed this:
~~docs: Add `doc/bitcoin-conf.md`~~
docs: Add doc/bitcoin-conf.md
on Oct 20, 2018
fanquake commented at 6:36 AM on October 20, 2018: member

utACK 1fb3c16 Had a quick read through, looks correct 👍
laanwj merged this on Oct 20, 2018
laanwj closed this on Oct 20, 2018
laanwj referenced this in commit 6746a89519 on Oct 20, 2018
hebasto deleted the branch on Oct 20, 2018
jasonbcox referenced this in commit cc70f06e3b on Oct 12, 2020
PastaPastaPasta referenced this in commit 7644b0fa8e on Jun 27, 2021
PastaPastaPasta referenced this in commit 1454380ea9 on Jun 28, 2021
PastaPastaPasta referenced this in commit 931802b239 on Jun 29, 2021
PastaPastaPasta referenced this in commit 8a9b3ff5f1 on Jul 1, 2021
PastaPastaPasta referenced this in commit 868f071b9f on Jul 1, 2021
PastaPastaPasta referenced this in commit 30cdf9c6f7 on Jul 1, 2021
PastaPastaPasta referenced this in commit 787113a778 on Jul 3, 2021
MarcoFalke locked this on Sep 8, 2021

Contributors

Labels

Linked (view graph)

#14370 utils and libraries: Allow values quoting in config files #14427 docs: Add config file docs to '-help' messages #14494 Error if # is used in rpcpassword in conf