doc: Add detailed info about Bitcoin Core files #16983

hebasto commented at 3:56 PM on September 29, 2019: member

This PR:

provides detailed info about the Bitcoin Core files;
does not mention temporary files, e.g., mempool.dat.new and peers.????

DrahtBot added the label Docs on Sep 29, 2019

promag commented at 8:50 PM on September 29, 2019: member

Overall LGTM. Could mention in PR/commit description that references to 0.8.0 are dropped.

hebasto commented at 5:27 AM on September 30, 2019: member

Could mention in PR/commit description that references to 0.8.0 are dropped.

The PR description has been updated.

laanwj commented at 9:39 AM on September 30, 2019: member

PR/commit description that references to 0.8.0 are dropped.

I think it makes sense to keep a list the "legacy files" somewhere, so that people encountering them (in old installs) have something to search for, and know they are no longer necessary and can be removed. Even if you drop mention of exact versions and meanings.

hebasto commented at 9:51 AM on September 30, 2019: member

I think it makes sense to keep a list the "legacy files" somewhere, so that people encountering them (in old installs) have something to search for, and know they are no longer necessary and can be removed. Even if you drop mention of exact versions and meanings.

Agree. Currently a user can choose any branch from 0.14 to 0.18 in GitHub web interface. Could it be "somewhere" that keeps a list of legacy files?

laanwj commented at 12:50 PM on September 30, 2019: member

Please keep it in this document.

fanquake added the label Waiting for author on Oct 1, 2019

hebasto commented at 10:35 AM on October 1, 2019: member

Please keep it in this document.

Done.

fanquake removed the label Waiting for author on Oct 1, 2019

ch4ot1c commented at 5:14 AM on October 2, 2019: contributor

Concept ACK.

I like the direction of this @hebasto. Some suggestions:

holds->contains
custom->custom format, could even link or add information about the format
block chain->blockchain
bitcoin.conf could have a reference to the example (share/examples/bitcoin.conf)
database/ contains data, not BDB logs
Capitalize each line in Description
Using datadir/ and wallet_name as literals is confusing
* NOTE: could be a blockquote or footnote; regexp->regex
** NOTE: could be a blockquote or footnote, or maybe inlined
blocks/index/: How do I set a custom path via CLI?
Chain option No option could spell out the -mainnet flag

Also, here's another interpretation of the table of contents / section titles, if useful:

1. Datadir location
2. Datadir layout
3. Wallet files
  - Default, single wallet layout
  - Multi-wallet layout
4. Other files
  - QSettings
5. Legacy files and directories

hebasto commented at 12:02 PM on October 2, 2019: member

@ch4ot1c

database/ contains data, not BDB logs

Considering: https://github.com/bitcoin/bitcoin/blob/30c2b0b1cb110c27e329e453210561ea5dcdbeb5/src/wallet/db.cpp#L190

and https://docs.oracle.com/cd/E17076_01/html/api_reference/C/envset_lg_dir.html, I believe the contents of the database/ are BDB logging files.

laanwj commented at 12:10 PM on October 2, 2019: member

BDB log files are part of the data though—comparable with the journal in file systems, not as in the debug log (which means, most importantly, that it is not safe to just erase them).

doc: Add detailed info about Bitcoin Core files 86b9f92da2

hebasto force-pushed on Oct 2, 2019

hebasto commented at 6:55 PM on October 2, 2019: member

@ch4ot1c The most part of your suggestions has been implemented. Didn't catch the last two of them:

blocks/index/: How do I set a custom path via CLI?

Chain option No option could spell out the -mainnet flag

Would you mind re-wording your ideas?

ch4ot1c commented at 7:27 PM on October 2, 2019: contributor

Sure -

blocks/index/ - Block index; `-blocksdir` option does not affect this path - how do I affect this path?
no option (mainnet)->No option (or `-mainnet`)

hebasto commented at 6:03 PM on October 4, 2019: member

@ch4ot1c

* `blocks/index/` - `` Block index; `-blocksdir` option does not affect this path `` - how _do_ I affect this path?

Considering: https://github.com/bitcoin/bitcoin/blob/94d6a18f23ec1add600f04fc7bd0808b7384d829/src/txdb.cpp#L148-L149

there is no way to affect blocks/index/ path.

* `no option (mainnet)`->`` No option (or `-mainnet`) ``

Do we have -mainnet as command-line option?

ch4ot1c commented at 3:54 AM on October 5, 2019: contributor

-chain=main, but no. Good notes - thanks for mentioning!

ch4ot1c commented at 3:54 AM on October 5, 2019: contributor

ACK 86b9f92

MarcoFalke commented at 5:53 PM on October 7, 2019: member

Concept ACK

in doc/files.md:97 in 86b9f92da2

 129 | +`blk000?.dat`  | Block data (custom format, 2 GiB per file); replaced by `blocks/blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677)
 130 | +`addr.dat`     | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/bitcoin/bitcoin/pull/1198), [`928d3a01`](https://github.com/bitcoin/bitcoin/commit/928d3a011cc66c7f907c4d053f674ea77dc611cc)
 131 | +
 132 | +## Notes
 133 | +
 134 | +<a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this paper.

laanwj commented at 10:16 AM on October 9, 2019:

lol @ "in this paper"

laanwj commented at 10:16 AM on October 9, 2019: member

ACK 86b9f92da25f2768eb29eefd6526320135f39a2f this is much of an improvement

fanquake commented at 1:24 PM on October 9, 2019: member

@hebasto Can you update the PR description. The crossed out 0.8.0 seems incorrect now.

fanquake added the label Waiting for author on Oct 9, 2019

hebasto commented at 1:55 PM on October 9, 2019: member

@fanquake

Can you update the PR description. The crossed out 0.8.0 seems incorrect now.

Sure ;) Done.

fanquake removed the label Waiting for author on Oct 9, 2019

MarcoFalke commented at 7:58 PM on October 10, 2019: member

ACK 86b9f92da25f2768eb29eefd6526320135f39a2f

<details><summary>Show signature and timestamp</summary>

Signature:

Timestamp of file with hash 9f2ff8ea4a42ee5db2f108e51e215fb6faf8857556cb207b0fe9722786a9906b -

</details>

MarcoFalke referenced this in commit 08ed87e887 on Oct 10, 2019

MarcoFalke merged this on Oct 10, 2019

MarcoFalke closed this on Oct 10, 2019

hebasto deleted the branch on Oct 11, 2019

sidhujag referenced this in commit 889c5975d2 on Oct 11, 2019

hebasto commented at 8:06 PM on October 14, 2019: member

@ch4ot1c

* `no option (mainnet)`->`` No option (or `-mainnet`) ``

Oh! I missed that #16680 has been merged recently. It provides -chain=main ;)

jasonbcox referenced this in commit 86009464c7 on Oct 20, 2020

MarcoFalke locked this on Dec 16, 2021