Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from Oct 20, 2018
Merged

Conversation

@hebasto
Copy link
Member

@hebasto hebasto commented Oct 16, 2018

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.

Copy link
Contributor

@ryanofsky ryanofsky left a comment

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.


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.
Copy link
Contributor

@practicalswift practicalswift Oct 16, 2018

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

Copy link
Member

@laanwj laanwj Oct 17, 2018

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

@practicalswift
Copy link
Contributor

@practicalswift practicalswift commented Oct 16, 2018

utACK c25f444785ccf94b6c648ac65d919f759189516e

Very nicely written!

Copy link
Contributor

@jimmysong jimmysong left a comment

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

@@ -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.
Copy link
Contributor

@jimmysong jimmysong Oct 16, 2018

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

Copy link
Member

@laanwj laanwj Oct 17, 2018

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

@fanquake fanquake added the Docs label Oct 17, 2018

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]`.
Copy link
Member

@sipa sipa Oct 17, 2018

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

Copy link
Member

@laanwj laanwj Oct 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

@laanwj
Copy link
Member

@laanwj laanwj commented Oct 17, 2018

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

Copy link
Member

@promag promag left a comment

ACK.

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


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.
Copy link
Member

@promag promag Oct 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

vs

# reasons
foo=bar

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

@promag promag Oct 17, 2018

Drop Bitcoin?


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.
Copy link
Contributor

@flack flack Oct 18, 2018

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.


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]`.
Copy link
Contributor

@flack flack Oct 18, 2018

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 hebasto force-pushed the 20181016-bitcoin-conf-md branch from c25f444 to 36efaf6 Oct 18, 2018
@hebasto
Copy link
Member Author

@hebasto hebasto commented Oct 18, 2018

All comments are addressed. Please re-review.

@promag
Copy link
Member

@promag promag commented Oct 18, 2018


## 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.
Copy link
Contributor

@flack flack Oct 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
Copy link
Member Author

@hebasto hebasto commented Oct 18, 2018

@promag
Copy link
Member

@promag promag commented Oct 18, 2018

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

@hebasto
Copy link
Member Author

@hebasto hebasto commented Oct 18, 2018

@promag The PR description has been updated.

@hebasto hebasto force-pushed the 20181016-bitcoin-conf-md branch from 36efaf6 to 1fb3c16 Oct 18, 2018
@hebasto
Copy link
Member Author

@hebasto hebasto commented Oct 18, 2018

@flack Fixed.

@sipa
Copy link
Member

@sipa sipa commented Oct 20, 2018

utACK 1fb3c16

@MarcoFalke
Copy link
Member

@MarcoFalke MarcoFalke commented Oct 20, 2018

ACK 1fb3c16

@fanquake fanquake changed the title docs: Add doc/bitcoin-conf.md docs: Add doc/bitcoin-conf.md Oct 20, 2018
@fanquake
Copy link
Member

@fanquake fanquake commented Oct 20, 2018

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

@laanwj laanwj merged commit 1fb3c16 into bitcoin:master Oct 20, 2018
2 checks passed
laanwj added a commit that referenced this issue Oct 20, 2018
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
@hebasto hebasto deleted the 20181016-bitcoin-conf-md branch Oct 20, 2018
jasonbcox pushed a commit to Bitcoin-ABC/bitcoin-abc that referenced this issue Oct 12, 2020
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jun 27, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jun 28, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jun 29, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jul 1, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jul 1, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jul 1, 2021
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
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this issue Jul 3, 2021
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
@bitcoin bitcoin locked as resolved and limited conversation to collaborators Sep 8, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

10 participants