From 5efd3611f8132fac10b20add42df2bc796e6ae3e Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum Date: Tue, 20 Dec 2022 18:49:50 +0200 Subject: [PATCH 1/6] Removed typo --- .swm/adding-a-command.JLzge.sw.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.swm/adding-a-command.JLzge.sw.md b/.swm/adding-a-command.JLzge.sw.md index ae76b5b07b..e68cbe8f10 100644 --- a/.swm/adding-a-command.JLzge.sw.md +++ b/.swm/adding-a-command.JLzge.sw.md @@ -137,14 +137,13 @@ The return value from the function becomes the exit status of the command. ```mermaid sequenceDiagram User Interface->>+Git CLI: git add -Git CLI->>+User Interface: John, can you hear me? Git CLI-->>chdir: If RUN_SETUP in commands chdir-->>Git CLI: set prefix to the path to the subdir Git CLI->>Command (add): prefix Command (add)->>Git CLI: return exit_status Git CLI->>+User Interface: return code ``` - +
From 9c3a3d4e055ee6407b4e41dfbc8b27abca6c37ef Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum <52040016+Omerr@users.noreply.github.com> Date: Mon, 2 Jan 2023 20:49:27 +0200 Subject: [PATCH 2/6] docs(swimm): update swimms: "CLI interaction" --- .swm/cli-interaction.vvxtv.sw.md | 73 ++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 .swm/cli-interaction.vvxtv.sw.md diff --git a/.swm/cli-interaction.vvxtv.sw.md b/.swm/cli-interaction.vvxtv.sw.md new file mode 100644 index 0000000000..8e8d406cd2 --- /dev/null +++ b/.swm/cli-interaction.vvxtv.sw.md @@ -0,0 +1,73 @@ +--- +id: vvxtv +name: CLI interaction +file_version: 1.1.0 +app_version: 1.0.0 +file_blobs: + builtin.h: 16ecd5586f0beeae1e65efb06f25836723d8f4e9 + git.c: 18bed9a99647aa310ad37d4cd8dc683c66084b41 + my_builtin/add.c: 17528e8f922693e2ec99aa66f3d761a3b83fcf35 +--- + +In this document, we will learn how data is sent to and from Git's CLI. + +# Commands and definitions + +
+ +The git commands must be declared within `📄 builtin.h`: + +### 📄 builtin.h +```c +⬜ 111 +⬜ 112 int is_builtin(const char *s); +⬜ 113 +🟩 114 int cmd_add(int argc, const char **argv, const char *prefix); +⬜ 115 int cmd_am(int argc, const char **argv, const char *prefix); +⬜ 116 int cmd_annotate(int argc, const char **argv, const char *prefix); +⬜ 117 int cmd_apply(int argc, const char **argv, const char *prefix); +``` + +
+ +# How your commands are called + +The implementation commands take three parameters: `argc`, `argv`, and `prefix`. The first two are similar to what `main()` of a standalone command would be called with. + +When `RUN_SETUP` is specified in the `commands` table, and when you were started from a subdirectory of the work tree, your new command (e.g., `cmd_add` is called after `chdir` to the top of the work tree, and `prefix` gets the path to the subdirectory the command started from. This allows you to convert a user-supplied pathname (typically relative to that directory) to a pathname relative to the top of the work tree. + +The return value from the function becomes the exit status of the command. + +
+ + +```mermaid +sequenceDiagram +User Interface->>+Git CLI: git `add` +Git CLI-->>chdir: If `RUN_SETUP` in `commands` +chdir-->>Git CLI: set `prefix` to the path to the subdir +Git CLI->>Command (add): `prefix` +Command (add)->>Git CLI: return `exit_status` +Git CLI->>+User Interface: return code +``` + + +
+ +To make Git “aware” of the `add` command, it needs to be registered by adding a `cmd_struct` to the `commands` array: + +### 📄 git.c +```c +⬜ 481 return 0; +⬜ 482 } +⬜ 483 +🟩 484 static struct cmd_struct commands[] = { +🟩 485 { "add", cmd_add, RUN_SETUP | NEED_WORK_TREE }, +⬜ 486 { "am", cmd_am, RUN_SETUP | NEED_WORK_TREE }, +⬜ 487 { "annotate", cmd_annotate, RUN_SETUP | NO_PARSEOPT }, +⬜ 488 { "apply", cmd_apply, RUN_SETUP_GENTLY }, +``` + +
+ +This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/vvxtv). From 4ce76a8e288a4b264fe46e1b385e8fc50356b754 Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum <52040016+Omerr@users.noreply.github.com> Date: Mon, 2 Jan 2023 21:10:34 +0200 Subject: [PATCH 3/6] docs(swimm): update swimms: "Contribution" --- .swm/contribution.p7eqt.sw.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .swm/contribution.p7eqt.sw.md diff --git a/.swm/contribution.p7eqt.sw.md b/.swm/contribution.p7eqt.sw.md new file mode 100644 index 0000000000..790db7c063 --- /dev/null +++ b/.swm/contribution.p7eqt.sw.md @@ -0,0 +1,18 @@ +--- +id: p7eqt +name: Contribution +file_version: 1.1.0 +app_version: 1.0.0 +--- + +## Contributing to git + +Thanks for taking the time to contribute to Git! Please be advised that the Git community does not use github.com for their contributions. + +Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. + +Nevertheless, you can use [GitGitGadget](https://gitgitgadget.github.io/) to conveniently send your Pull Requests commits to our mailing list. + +
+ +This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/p7eqt). From d31901acb88da919f5928a68500bb7819ac7a907 Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum <52040016+Omerr@users.noreply.github.com> Date: Mon, 2 Jan 2023 21:15:15 +0200 Subject: [PATCH 4/6] docs(swimm): update swimms: "My First Object Walk" --- .swm/my-first-object-walk.evxx4.sw.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .swm/my-first-object-walk.evxx4.sw.md diff --git a/.swm/my-first-object-walk.evxx4.sw.md b/.swm/my-first-object-walk.evxx4.sw.md new file mode 100644 index 0000000000..1348c136f6 --- /dev/null +++ b/.swm/my-first-object-walk.evxx4.sw.md @@ -0,0 +1,16 @@ +--- +id: evxx4 +name: My First Object Walk +file_version: 1.1.0 +app_version: 1.0.0 +--- + +## What's an object walk? + +The object walk is a key concept in Git - this is the process that underpins operations like object transfer and fsck. Beginning from a given commit, the list of objects is found by walking parent relationships between commits (commit X based on commit W) and containment relationships between objects (tree Y is contained within commit X, and blob Z is located within tree Y, giving our working tree for commit X something like `y/z.txt`). + +A related concept is the revision walk, which is focused on commit objects and their parent relationships and does not delve into other object types. The revision walk is used for operations like `git log`. + +
+ +This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/evxx4). From c8ab0189e16539657bb3123512ca165398bc3b16 Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum <52040016+Omerr@users.noreply.github.com> Date: Mon, 2 Jan 2023 21:23:31 +0200 Subject: [PATCH 5/6] docs(swimm): update swimms: "Error reporting in git" --- .swm/error-reporting-in-git.i3r5y.sw.md | 102 ++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 .swm/error-reporting-in-git.i3r5y.sw.md diff --git a/.swm/error-reporting-in-git.i3r5y.sw.md b/.swm/error-reporting-in-git.i3r5y.sw.md new file mode 100644 index 0000000000..81c30c3767 --- /dev/null +++ b/.swm/error-reporting-in-git.i3r5y.sw.md @@ -0,0 +1,102 @@ +--- +id: i3r5y +name: Error reporting in git +file_version: 1.1.0 +app_version: 1.0.0 +file_blobs: + daemon.c: 5c4cbad62d0caa723a874392097512a0df5933cd + branch.c: 7a88a4861e7eb41e5415f141d4d143170c8ca5e0 + usage.c: c7d233b0de9538951c5f3d47aa165d900034c02b + parse-options.c: 2abff136a17b1d37452695f8b06609a3176fa273 +--- + +`BUG`, `die`, `usage`, `error`, and `warning` report errors of various kinds. + +\- `BUG` is for failed internal assertions that should never happen, i.e. a bug in git itself. + +\- `die` is for fatal application errors. It prints a message to the user and exits with status 128. + +\- `usage` is for errors in command line usage. After printing its message, (See also `usage_with_options`) + +\- `error` is for non-fatal library errors. It prints a message to the user and returns -1 for convenience in signaling the error + +to the caller. + +\- `warning` is for reporting situations that probably should not occur but which the user (and Git) can continue to work around + +without running into too many problems. Like `error`, it returns -1 after reporting the situation to the caller. + +
+ +## Customizable error handlers + +The default behavior of `die` and `error` is to write a message to stderr and then exit or return as appropriate. This behavior can be + +overridden using `set_die_routine` and `set_error_routine`. + +
+ +
+ +For example, "git daemon" uses `set_die_routine` to write the reason `die` was called to syslog before exiting. + +### 📄 daemon.c +```c +🟩 1434 if (log_destination == LOG_DESTINATION_SYSLOG) { +🟩 1435 openlog("git-daemon", LOG_PID, LOG_DAEMON); +🟩 1436 set_die_routine(daemon_die); +🟩 1437 } else +``` + +
+ +# Caller-handled errors + +An increasing number of functions take a parameter `struct strbuf *err`. + +
+ +
+ +On error, such functions append a message about what went wrong to the `err` strbuf. The message is meant to be complete enough to be passed to `die` or `error` as-is. For example: + +### 📄 branch.c +```c +🟩 323 if (!transaction || +🟩 324 ref_transaction_update(transaction, ref.buf, +🟩 325 &oid, forcing ? NULL : null_oid(), +🟩 326 0, msg, &err) || +🟩 327 ref_transaction_commit(transaction, &err)) +🟩 328 die("%s", err.buf); +``` + +
+ +
+ +
+ +The 'err' parameter will be untouched if no error occurred, so multiple function calls can be chained: + +### 📄 branch.c +```c +🟩 322 transaction = ref_transaction_begin(&err); +🟩 323 if (!transaction || +🟩 324 ref_transaction_update(transaction, ref.buf, +🟩 325 &oid, forcing ? NULL : null_oid(), +🟩 326 0, msg, &err) || +🟩 327 ref_transaction_commit(transaction, &err)) +🟩 328 die("%s", err.buf); +🟩 329 ref_transaction_free(transaction); +🟩 330 strbuf_release(&err); +``` + +
+ +
+ +
+ +
+ +This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/i3r5y). From e60abeb89e5fdc8cf2b9c901d7f98b39ca97d9e6 Mon Sep 17 00:00:00 2001 From: Omer Rosenbaum <52040016+Omerr@users.noreply.github.com> Date: Tue, 3 Jan 2023 10:38:56 +0200 Subject: [PATCH 6/6] docs(swimm): update swimms: "CLI interaction" --- .swm/cli-interaction.vvxtv.sw.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.swm/cli-interaction.vvxtv.sw.md b/.swm/cli-interaction.vvxtv.sw.md index 8e8d406cd2..d75083b1d7 100644 --- a/.swm/cli-interaction.vvxtv.sw.md +++ b/.swm/cli-interaction.vvxtv.sw.md @@ -15,7 +15,7 @@ In this document, we will learn how data is sent to and from Git's CLI.
-The git commands must be declared within `📄 builtin.h`: +The git commands must be declared within `📄 builtin.h`, for example: ### 📄 builtin.h ```c @@ -23,9 +23,15 @@ The git commands must be declared within `📄 builtin.h`: ⬜ 112 int is_builtin(const char *s); ⬜ 113 🟩 114 int cmd_add(int argc, const char **argv, const char *prefix); -⬜ 115 int cmd_am(int argc, const char **argv, const char *prefix); -⬜ 116 int cmd_annotate(int argc, const char **argv, const char *prefix); -⬜ 117 int cmd_apply(int argc, const char **argv, const char *prefix); +🟩 115 int cmd_am(int argc, const char **argv, const char *prefix); +🟩 116 int cmd_annotate(int argc, const char **argv, const char *prefix); +🟩 117 int cmd_apply(int argc, const char **argv, const char *prefix); +🟩 118 int cmd_archive(int argc, const char **argv, const char *prefix); +🟩 119 int cmd_bisect__helper(int argc, const char **argv, const char *prefix); +🟩 120 int cmd_blame(int argc, const char **argv, const char *prefix); +⬜ 121 int cmd_branch(int argc, const char **argv, const char *prefix); +⬜ 122 int cmd_bugreport(int argc, const char **argv, const char *prefix); +⬜ 123 int cmd_bundle(int argc, const char **argv, const char *prefix); ```