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

hebasto · 2018-10-16T21:18:05Z

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:

Based on the BITCOIN.CONF(5) manual page written by Micah Anderson <micah@debian.org> for the Debian system.

ryanofsky

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.

practicalswift · 2018-10-16T22:15:04Z

doc/bitcoin-conf.md

+
+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.
+
+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.


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

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

practicalswift · 2018-10-16T22:15:41Z

utACK c25f444785ccf94b6c648ac65d919f759189516e

Very nicely written!

jimmysong

Great initiative! I'd love to see a commented example as a way to describe what some options do.

jimmysong · 2018-10-16T23:52:47Z

doc/bitcoin-conf.md

@@ -0,0 +1,11 @@
+# `bitcoin.conf` - Bitcoin configuration file
+
+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.


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

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

sipa · 2018-10-17T07:09:21Z

doc/bitcoin-conf.md

+
+The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files.
+
+Network specific options can be placed into the sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) and `[regtest]`.


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

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

laanwj · 2018-10-17T14:04:04Z

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

promag

ACK.

Could mention that this configuration is used by bitcoind, bitcoin-qt and bitcoin-cli?

promag · 2018-10-17T15:07:32Z

doc/bitcoin-conf.md

+
+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.
+
+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.


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

foo=bar # reasons

vs

# reasons foo=bar

promag · 2018-10-17T15:08:30Z

doc/bitcoin-conf.md

@@ -0,0 +1,11 @@
+# `bitcoin.conf` - Bitcoin configuration file


Drop Bitcoin?

flack · 2018-10-18T16:51:55Z

doc/bitcoin-conf.md

+
+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.
+
+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.


Suggested change

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.

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.

flack · 2018-10-18T16:53:58Z

doc/bitcoin-conf.md

+
+The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files.
+
+Network specific options can be placed into the sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) and `[regtest]`.


Suggested change

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

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

hebasto · 2018-10-18T21:04:11Z

All comments are addressed. Please re-review.

promag · 2018-10-18T21:19:47Z

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

flack · 2018-10-18T21:46:20Z

doc/bitcoin-conf.md

+
+## Configuration File Path
+
+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.


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 · 2018-10-18T21:54:57Z

@promag

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

How?

promag · 2018-10-18T21:59:11Z

@hebasto not sure, maybe in the PR description which will be in the merge commit?

hebasto · 2018-10-18T22:06:55Z

@promag The PR description has been updated.

hebasto · 2018-10-18T22:15:33Z

@flack Fixed.

sipa · 2018-10-20T02:07:23Z

utACK 1fb3c16

maflcko · 2018-10-20T06:28:10Z

ACK 1fb3c16

fanquake · 2018-10-20T06:36:50Z

utACK 1fb3c16
Had a quick read through, looks correct 👍

1fb3c16 Add `doc/bitcoin-conf.md` (Hennadii Stepanov) Pull request description: 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. Tree-SHA512: 16393c9073c027fa1c46f8b59651e60b9a3159b3aeb9b3102040c292d2787f32b1ead5977957ac3ac0759a4bf626650a2325b68ad84320964ac089ffc2d3b4f4

Summary: Backport of Core [[bitcoin/bitcoin#14497 | PR14497]] Test Plan: Proofreading with a markdown viewer Reviewers: O1 Bitcoin ABC, #bitcoin_abc, deadalnix Reviewed By: O1 Bitcoin ABC, #bitcoin_abc, deadalnix Differential Revision: https://reviews.bitcoinabc.org/D7890

1fb3c16 Add `doc/bitcoin-conf.md` (Hennadii Stepanov) Pull request description: 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: - bitcoin#14370 - bitcoin#14427 - bitcoin#14494 Based on the BITCOIN.CONF(5) manual page written by Micah Anderson \<micah@debian.org\> for the Debian system. Tree-SHA512: 16393c9073c027fa1c46f8b59651e60b9a3159b3aeb9b3102040c292d2787f32b1ead5977957ac3ac0759a4bf626650a2325b68ad84320964ac089ffc2d3b4f4

ryanofsky approved these changes Oct 16, 2018

View reviewed changes

practicalswift reviewed Oct 16, 2018

View reviewed changes

jimmysong reviewed Oct 16, 2018

View reviewed changes

fanquake added the Docs label Oct 17, 2018

sipa reviewed Oct 17, 2018

View reviewed changes

promag reviewed Oct 17, 2018

View reviewed changes

laanwj mentioned this pull request Oct 18, 2018

utils and libraries: Allow values quoting in config files #14370

Closed

hebasto mentioned this pull request Oct 18, 2018

docs: Add config file docs to '-help' messages #14427

Closed

flack reviewed Oct 18, 2018

View reviewed changes

hebasto force-pushed the 20181016-bitcoin-conf-md branch from c25f444 to 36efaf6 Compare October 18, 2018 21:01

flack reviewed Oct 18, 2018

View reviewed changes

Add doc/bitcoin-conf.md

1fb3c16

hebasto force-pushed the 20181016-bitcoin-conf-md branch from 36efaf6 to 1fb3c16 Compare October 18, 2018 22:14

fanquake changed the title ~~docs: Add doc/bitcoin-conf.md~~ docs: Add doc/bitcoin-conf.md Oct 20, 2018

laanwj merged commit 1fb3c16 into bitcoin:master Oct 20, 2018

hebasto deleted the 20181016-bitcoin-conf-md branch October 20, 2018 07:28

bitcoin locked as resolved and limited conversation to collaborators Sep 8, 2021


		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.

		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.

		@@ -0,0 +1,11 @@
		# `bitcoin.conf` - Bitcoin configuration file

		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.


		The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files.

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


		## Configuration File Path

		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.

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

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

Uh oh!

Conversation

hebasto commented Oct 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ryanofsky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

practicalswift commented Oct 16, 2018

Uh oh!

jimmysong left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

laanwj commented Oct 17, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

promag left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hebasto commented Oct 18, 2018

Uh oh!

promag commented Oct 18, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hebasto commented Oct 18, 2018

Uh oh!

promag commented Oct 18, 2018

Uh oh!

hebasto commented Oct 18, 2018

Uh oh!

hebasto commented Oct 18, 2018

Uh oh!

sipa commented Oct 20, 2018

Uh oh!

maflcko commented Oct 20, 2018

Uh oh!

fanquake commented Oct 20, 2018

Uh oh!

Uh oh!

hebasto commented Oct 16, 2018 •

edited

Loading

laanwj commented Oct 17, 2018 •

edited

Loading