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

Conversation

Projects
None yet
10 participants
@hebasto
Copy link
Member

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.

@ryanofsky
Copy link
Contributor

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.

doc/bitcoin-conf.md Outdated

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.

This comment has been minimized.

Copy link
@practicalswift

practicalswift Oct 16, 2018

Member

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

This comment has been minimized.

Copy link
@laanwj

laanwj Oct 17, 2018

Member

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

@practicalswift

This comment has been minimized.

Copy link
Member

commented Oct 16, 2018

utACK c25f444785ccf94b6c648ac65d919f759189516e

Very nicely written!

@jimmysong
Copy link
Contributor

left a comment

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

doc/bitcoin-conf.md Outdated
@@ -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.

This comment has been minimized.

Copy link
@jimmysong

jimmysong Oct 16, 2018

Contributor

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

This comment has been minimized.

Copy link
@laanwj

laanwj Oct 17, 2018

Member

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

doc/bitcoin-conf.md Outdated

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]`.

This comment has been minimized.

Copy link
@sipa

sipa Oct 17, 2018

Member

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

This comment has been minimized.

Copy link
@laanwj

laanwj Oct 17, 2018

Member

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

This comment has been minimized.

Copy link
Member

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

@promag
Copy link
Member

left a comment

ACK.

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

doc/bitcoin-conf.md Outdated

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.

This comment has been minimized.

Copy link
@promag

promag Oct 17, 2018

Member

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

This comment has been minimized.

Copy link
@promag

promag Oct 17, 2018

Member

Drop Bitcoin?

doc/bitcoin-conf.md Outdated

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.

This comment has been minimized.

Copy link
@flack

flack Oct 18, 2018

Contributor
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.
doc/bitcoin-conf.md Outdated

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]`.

This comment has been minimized.

Copy link
@flack

flack Oct 18, 2018

Contributor
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 hebasto:20181016-bitcoin-conf-md branch Oct 18, 2018

@hebasto

This comment has been minimized.

Copy link
Member Author

commented Oct 18, 2018

All comments are addressed. Please re-review.

@promag

This comment has been minimized.

Copy link
Member

commented Oct 18, 2018

doc/bitcoin-conf.md Outdated

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

This comment has been minimized.

Copy link
@flack

flack Oct 18, 2018

Contributor

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

This comment has been minimized.

Copy link
Member Author

commented Oct 18, 2018

@promag

This comment has been minimized.

Copy link
Member

commented Oct 18, 2018

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

@hebasto

This comment has been minimized.

Copy link
Member Author

commented Oct 18, 2018

@promag The PR description has been updated.

@hebasto hebasto force-pushed the hebasto:20181016-bitcoin-conf-md branch to 1fb3c16 Oct 18, 2018

@hebasto

This comment has been minimized.

Copy link
Member Author

commented Oct 18, 2018

@flack Fixed.

@sipa

This comment has been minimized.

Copy link
Member

commented Oct 20, 2018

utACK 1fb3c16

@MarcoFalke

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link
Member

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

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

laanwj added a commit that referenced this pull request Oct 20, 2018

Merge #14497: docs: Add doc/bitcoin-conf.md
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 hebasto:20181016-bitcoin-conf-md branch Oct 20, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.