Normalize markdown formatting in documentation
- Use consistent dash-style bullet points - Remove trailing whitespace - Add missing blank lines between sections - Add trailing newline to README.md
This commit is contained in:
parent
dae6c64e24
commit
61c17ca585
20
CLAUDE.md
20
CLAUDE.md
@ -1,20 +1,20 @@
|
||||
# Important Rules
|
||||
|
||||
* when fixing a bug, write a failing test FIRST. only after the test fails, write
|
||||
the code to fix the bug. then ensure the test passes. leave the test in
|
||||
place and commit it with the bugfix. don't run shell commands to test
|
||||
bugfixes or reproduce bugs. write tests!
|
||||
- when fixing a bug, write a failing test FIRST. only after the test fails, write
|
||||
the code to fix the bug. then ensure the test passes. leave the test in
|
||||
place and commit it with the bugfix. don't run shell commands to test
|
||||
bugfixes or reproduce bugs. write tests!
|
||||
|
||||
* never, ever mention claude or anthropic in commit messages. do not use attribution
|
||||
- never, ever mention claude or anthropic in commit messages. do not use attribution
|
||||
|
||||
* after each change, run "make fmt".
|
||||
- after each change, run "make fmt".
|
||||
|
||||
* after each change, run "make test" and ensure all tests pass.
|
||||
- after each change, run "make test" and ensure all tests pass.
|
||||
|
||||
* after each change, run "make lint" and ensure no linting errors. fix any
|
||||
- after each change, run "make lint" and ensure no linting errors. fix any
|
||||
you find, one by one.
|
||||
|
||||
* after each change, commit the files you've changed. push after
|
||||
- after each change, commit the files you've changed. push after
|
||||
committing.
|
||||
|
||||
* NEVER use `git add -A`. always add only individual files that you've changed.
|
||||
- NEVER use `git add -A`. always add only individual files that you've changed.
|
||||
|
||||
36
README.md
36
README.md
@ -3,25 +3,25 @@
|
||||
[mfer](https://git.eeqj.de/sneak/mfer) is a reference implementation library
|
||||
and thin wrapper command-line utility written in [Go](https://golang.org)
|
||||
and first published in 2022 under the [WTFPL](https://wtfpl.net) (public
|
||||
domain) license. It specifies and generates `.mf` manifest files over a
|
||||
domain) license. It specifies and generates `.mf` manifest files over a
|
||||
directory tree of files to encapsulate metadata about them (such as
|
||||
cryptographic checksums or signatures over same) to aid in archiving,
|
||||
downloading, and streaming, or mirroring. The manifest files' data is
|
||||
downloading, and streaming, or mirroring. The manifest files' data is
|
||||
serialized with Google's [protobuf serialization
|
||||
format](https://developers.google.com/protocol-buffers). The structure of
|
||||
format](https://developers.google.com/protocol-buffers). The structure of
|
||||
these files can be found [in the format
|
||||
specification](https://git.eeqj.de/sneak/mfer/src/branch/main/mfer/mf.proto)
|
||||
which is included in the [project
|
||||
repository](https://git.eeqj.de/sneak/mfer).
|
||||
|
||||
The current version is pre-1.0 and while the repo was published in 2022,
|
||||
there has not yet been any versioned release. [SemVer](https://semver.org)
|
||||
there has not yet been any versioned release. [SemVer](https://semver.org)
|
||||
will be used for releases.
|
||||
|
||||
This project was started by [@sneak](https://sneak.berlin) to scratch an
|
||||
itch in 2022 and is currently a one-person effort, though the goal is for
|
||||
this to emerge as a de-facto standard and be incorporated into other
|
||||
software. A compatible javascript library is planned.
|
||||
software. A compatible javascript library is planned.
|
||||
|
||||
# Phases
|
||||
|
||||
@ -57,6 +57,7 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## cmd/mfer/
|
||||
|
||||
### main.go
|
||||
|
||||
- **Variables**
|
||||
- `Appname string` - Application name
|
||||
- `Version string` - Version string (set at build time)
|
||||
@ -65,12 +66,14 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## internal/cli/
|
||||
|
||||
### entry.go
|
||||
|
||||
- **Variables**
|
||||
- `NO_COLOR bool` - Disables color output when NO_COLOR env var is set
|
||||
- **Functions**
|
||||
- `Run(Appname, Version, Gitrev string) int` - Main entry point for the CLI
|
||||
|
||||
### mfer.go
|
||||
|
||||
- **Types**
|
||||
- `CLIApp struct` - Main CLI application container
|
||||
- **Methods**
|
||||
@ -79,6 +82,7 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## internal/log/
|
||||
|
||||
### log.go
|
||||
|
||||
- **Functions**
|
||||
- `Init()` - Initializes the logger
|
||||
- `Info(arg string)` - Logs at info level
|
||||
@ -99,6 +103,7 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## internal/scanner/
|
||||
|
||||
### scanner.go
|
||||
|
||||
- **Types**
|
||||
- `Options struct` - Options for scanner behavior
|
||||
- `IncludeDotfiles bool` - Include dot (hidden) files (excluded by default)
|
||||
@ -138,6 +143,7 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## internal/checker/
|
||||
|
||||
### checker.go
|
||||
|
||||
- **Types**
|
||||
- `Result struct` - Outcome of checking a single file
|
||||
- `Path string` - File path from manifest
|
||||
@ -169,12 +175,14 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
## mfer/
|
||||
|
||||
### manifest.go
|
||||
|
||||
- **Types**
|
||||
- `manifest struct` - Internal representation of a manifest file
|
||||
- **Methods**
|
||||
- `(*manifest) Files() []*MFFilePath` - Returns all file entries from a loaded manifest
|
||||
|
||||
### builder.go
|
||||
|
||||
- **Types**
|
||||
- `FileHashProgress struct` - Progress info during file hashing (BytesRead int64)
|
||||
- `Builder struct` - Constructs manifests by adding files one at a time
|
||||
@ -182,20 +190,23 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
- `NewBuilder() *Builder` - Creates a new Builder
|
||||
- **Methods**
|
||||
- `(*Builder) AddFile(path string, size int64, mtime time.Time, reader io.Reader, progress chan<- FileHashProgress) (int64, error)` - Reads file, computes hash, adds to manifest
|
||||
- `(*Builder) AddFileWithHash(path string, size int64, mtime time.Time, hash []byte)` - Adds file with pre-computed hash
|
||||
- `(*Builder) AddFileWithHash(path string, size int64, mtime time.Time, hash []byte) error` - Adds file with pre-computed hash
|
||||
- `(*Builder) FileCount() int` - Returns number of files added
|
||||
- `(*Builder) Build(w io.Writer) error` - Finalizes and writes manifest
|
||||
|
||||
### serialize.go
|
||||
|
||||
- **Constants**
|
||||
- `MAGIC string` - Magic bytes prefix for manifest files ("ZNAVSRFG")
|
||||
|
||||
### deserialize.go
|
||||
|
||||
- **Functions**
|
||||
- `NewManifestFromReader(input io.Reader) (*manifest, error)` - Reads and parses manifest from io.Reader
|
||||
- `NewManifestFromFile(fs afero.Fs, path string) (*manifest, error)` - Reads and parses manifest from file path
|
||||
|
||||
### mf.pb.go (generated from mf.proto)
|
||||
|
||||
- **Enum Types**
|
||||
- `MFFileOuter_Version` - Outer file format version
|
||||
- `MFFileOuter_VERSION_NONE`
|
||||
@ -241,19 +252,18 @@ Reading file contents and computing cryptographic hashes for manifest generation
|
||||
# Participation
|
||||
|
||||
The community is as yet nonexistent so there are no defined policies or
|
||||
norms yet. Primary development happens on a privately-run Gitea instance at
|
||||
norms yet. Primary development happens on a privately-run Gitea instance at
|
||||
[https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer) and issues
|
||||
are [tracked there](https://git.eeqj.de/sneak/mfer/issues).
|
||||
|
||||
Changes must always be formatted with a standard `go fmt`, syntactically
|
||||
valid, and must pass the linting defined in the repository (presently only
|
||||
the `golangci-lint` defaults), which can be run with a `make lint`. The
|
||||
the `golangci-lint` defaults), which can be run with a `make lint`. The
|
||||
`main` branch is protected and all changes must be made via [pull
|
||||
requests](https://git.eeqj.de/sneak/mfer/pulls) and pass CI to be merged.
|
||||
Any changes submitted to this project must also be
|
||||
[WTFPL-licensed](https://wtfpl.net) to be considered.
|
||||
|
||||
|
||||
# Problem Statement
|
||||
|
||||
Given a plain URL, there is no standard way to safely and programmatically
|
||||
@ -424,13 +434,13 @@ desired username for an account on this Gitea instance.
|
||||
|
||||
## Links
|
||||
|
||||
* Repo: [https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer)
|
||||
* Issues: [https://git.eeqj.de/sneak/mfer/issues](https://git.eeqj.de/sneak/mfer/issues)
|
||||
- Repo: [https://git.eeqj.de/sneak/mfer](https://git.eeqj.de/sneak/mfer)
|
||||
- Issues: [https://git.eeqj.de/sneak/mfer/issues](https://git.eeqj.de/sneak/mfer/issues)
|
||||
|
||||
# Authors
|
||||
|
||||
* [@sneak <sneak@sneak.berlin>](mailto:sneak@sneak.berlin)
|
||||
- [@sneak <sneak@sneak.berlin>](mailto:sneak@sneak.berlin)
|
||||
|
||||
# License
|
||||
|
||||
* [WTFPL](https://wtfpl.net)
|
||||
- [WTFPL](https://wtfpl.net)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user