Initial version of ARCHITECTURE.md

[dandavison]

@th1000s @WayneD @ulwlu @clnoll @unphased @dhduvall @Kr1ss-XD @norisio @maximbaz

This is an initial draft of a guide to the codebase to help people who are working on delta or considering it. Any thoughts, and additions, welcome!

https://github.com/dandavison/delta/blob/architecture-doc/ARCHITECTURE.md

[ghost]

Hi dandavison.
This is a bit of a long greeting, but it's been a while.
I'm sorry I can't contribute much this year,
but I have introduced delta to many engineers in Japan and they are using it.
Thanks for making a really great tool, including vscode and other viewers, but I still like delta the best.

As for architecture.md, it looks like it is a very good walk through to me.
The code has been refactored and changed quite a bit since I used to participate in the development,
but I was able to understand it quickly.

It might be a good idea to focus only on data flow, data structures, and algorithms,
as writing a code-map as well like the rust-analyzer might be difficult to maintain.

However, I think one of the purposes of architectures.md is to be a good help for new contributors.
Because if you don't know anything, it takes a lot of time to figure out "what code to change" and so on.
I often spend hours using git blame and ripgrep to go through the code and history (It's just my experience).

Come to think of it, I think it's worth writing only one description for each file in overview tree-file, probably?
Of course, you can see what it is doing by looking at the comments in the file.
However, I think it is easier for a beginner to understand the architecture by looking at the whole tree and seeing only one line of explanation.
And this isn't maybe that difficult to maintain.
When the file structure changes, you only need to change the tree for that part of the file, so you only need to change one line per file.

It's just a opinion, I would like to see other's one too!

src/
├── ansi/
│  ├── console_tests.rs # ......
│  ├── iterator.rs # .....
│  └── mod.rs
├── features/
│  ├── color_only.rs
│  ├── diff_highlight.rs
│  ├── diff_so_fancy.rs
│  ├── hyperlinks.rs
│  ├── line_numbers.rs
│  ├── mod.rs
│  ├── navigate.rs
│  ├── raw.rs
│  └── side_by_side.rs
├── git_config/
│  ├── git_config_entry.rs
│  └── mod.rs
├── handlers/
│  ├── blame.rs
│  ├── commit_meta.rs
│  ├── diff_stat.rs
│  ├── draw.rs
│  ├── file_meta.rs
│  ├── file_meta_diff.rs
│  ├── file_meta_misc.rs
│  ├── git_show_file.rs
│  ├── grep.rs
│  ├── hunk.rs
│  ├── hunk_header.rs
│  ├── mod.rs
│  ├── ripgrep_json.rs
│  └── submodule.rs
├── options/
│  ├── get.rs
│  ├── mod.rs
│  ├── option_value.rs
│  ├── rewrite.rs
│  ├── set.rs
│  └── theme.rs
├── subcommands/
│  ├── diff.rs
│  ├── list_syntax_themes.rs
│  ├── mod.rs
│  ├── parse_ansi.rs
│  ├── sample_diff.rs
│  ├── show_colors.rs
│  ├── show_config.rs
│  ├── show_syntax_themes.rs
│  └── show_themes.rs
├── tests/
│  ├── ansi_test_utils.rs
│  ├── integration_test_utils.rs
│  ├── mod.rs
│  ├── test_example_diffs.rs
│  └── test_utils.rs
├── utils/
│  ├── bat/
│  │  ├── assets.rs
│  │  ├── dirs.rs
│  │  ├── less.rs
│  │  ├── LICENSE
│  │  ├── mod.rs
│  │  ├── output.rs
│  │  └── terminal.rs
│  ├── mod.rs
│  ├── process.rs
│  └── syntect.rs
├── align.rs
├── cli.rs
├── color.rs
├── colors.rs
├── config.rs
├── delta.rs
├── edits.rs
├── env.rs
├── format.rs
├── main.rs
├── minusplus.rs
├── paint.rs
├── parse_style.rs
├── parse_styles.rs
├── style.rs
└── wrapping.rs

[dandavison]

Hi @ulwlu, thanks! That's a good suggestion of an annotated file tree. (However, I do wonder whether it might be even better to consistently put those module explanations on the first line of every file and then give the users a shell one-liner to print out the annotated file tree.)

[ghost]

um maybe that's easier as you wrote. I don't know if there is any command can achieve by default, since even tree command doesn't exist in mac at default.

But exa, grep, head (or fd, as-tree, head) combination can.I can add that script when you need and tell me! @dandavison