CLI interaction

.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
 ```
-<!--MCONTENT {content: "sequenceDiagram<br/>\nUser Interface->>+Git CLI: git `add`[<sup id=\"ZY0bfT\">↓</sup>](#f-ZY0bfT)<br/>\nGit CLI->>+User Interface: John, can you hear me?<br/>\nGit CLI\\-\\-\\>>chdir: If `RUN_SETUP`[<sup id=\"Z1BE9pN\">↓</sup>](#f-Z1BE9pN) in `commands`[<sup id=\"ZAY7QK\">↓</sup>](#f-ZAY7QK)<br/>\nchdir\\-\\-\\>>Git CLI: set `prefix`[<sup id=\"2bcG0g\">↓</sup>](#f-2bcG0g) to the path to the subdir<br/>\nGit CLI->>Command (add): `prefix`[<sup id=\"2bcG0g\">↓</sup>](#f-2bcG0g)<br/>\nCommand (add)->>Git CLI: return `exit_status`[<sup id=\"25O6Qg\">↓</sup>](#f-25O6Qg)<br/>\nGit CLI->>+User Interface: return code"} --->
+<!--MCONTENT {content: "sequenceDiagram<br/>\nUser Interface->>+Git CLI: git `add`[<sup id=\"ZY0bfT\">↓</sup>](#f-ZY0bfT)<br/>\nGit CLI\\-\\-\\>>chdir: If `RUN_SETUP`[<sup id=\"Z1BE9pN\">↓</sup>](#f-Z1BE9pN) in `commands`[<sup id=\"ZAY7QK\">↓</sup>](#f-ZAY7QK)<br/>\nchdir\\-\\-\\>>Git CLI: set `prefix`[<sup id=\"2bcG0g\">↓</sup>](#f-2bcG0g) to the path to the subdir<br/>\nGit CLI->>Command (add): `prefix`[<sup id=\"2bcG0g\">↓</sup>](#f-2bcG0g)<br/>\nCommand (add)->>Git CLI: return `exit_status`[<sup id=\"25O6Qg\">↓</sup>](#f-25O6Qg)<br/>\nGit CLI->>+User Interface: return code"} --->
 
 <br/>
 

.swm/cli-interaction.vvxtv.sw.md

@@ -0,0 +1,79 @@
+---
+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
+
+<br/>
+
+The git commands must be declared within `📄 builtin.h`, for example:
+<!-- NOTE-swimm-snippet: the lines below link your snippet to Swimm -->
+### 📄 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);
+🟩 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);
+```
+
+<br/>
+
+# How your commands are called
+
+The implementation commands take three parameters: `argc`<swm-token data-swm-token=":my_builtin/add.c:475:6:6:`int cmd_add(int argc, const char **argv, const char *prefix)`"/>, `argv`<swm-token data-swm-token=":builtin.h:114:14:14:`int cmd_add(int argc, const char **argv, const char *prefix);`"/>, and `prefix`<swm-token data-swm-token=":builtin.h:114:22:22:`int cmd_add(int argc, const char **argv, const char *prefix);`"/>. The first two are similar to what `main()` of a standalone command would be called with.
+
+When `RUN_SETUP`<swm-token data-swm-token=":git.c:485:11:11:`	{ &quot;add&quot;, cmd_add, RUN_SETUP | NEED_WORK_TREE },`"/> is specified in the `commands`<swm-token data-swm-token=":git.c:484:6:6:`static struct cmd_struct commands[] = {`"/> table, and when you were started from a subdirectory of the work tree, your new command (e.g., `cmd_add`<swm-token data-swm-token=":builtin.h:114:2:2:`int cmd_add(int argc, const char **argv, const char *prefix);`"/> is called after `chdir` to the top of the work tree, and `prefix`<swm-token data-swm-token=":my_builtin/add.c:475:22:22:`int cmd_add(int argc, const char **argv, const char *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.
+
+<br/>
+
+<!--MERMAID {width:100}-->
+```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
+```
+<!--MCONTENT {content: "sequenceDiagram<br/>\nUser Interface->>+Git CLI: git `add`<swm-token data-swm-token=\":git.c:485:4:4:`\t{ &quot;add&quot;, cmd_add, RUN_SETUP | NEED_WORK_TREE },`\"/><br/>\nGit CLI\\-\\-\\>>chdir: If `RUN_SETUP`<swm-token data-swm-token=\":git.c:485:11:11:`\t{ &quot;add&quot;, cmd_add, RUN_SETUP | NEED_WORK_TREE },`\"/> in `commands`<swm-token data-swm-token=\":git.c:484:6:6:`static struct cmd_struct commands[] = {`\"/><br/>\nchdir\\-\\-\\>>Git CLI: set `prefix`<swm-token data-swm-token=\":builtin.h:114:22:22:`int cmd_add(int argc, const char **argv, const char *prefix);`\"/> to the path to the subdir<br/>\nGit CLI->>Command (add): `prefix`<swm-token data-swm-token=\":builtin.h:114:22:22:`int cmd_add(int argc, const char **argv, const char *prefix);`\"/><br/>\nCommand (add)->>Git CLI: return `exit_status`<swm-token data-swm-token=\":my_builtin/add.c:472:3:3:`\treturn exit_status;`\"/><br/>\nGit CLI->>+User Interface: return code"} --->
+
+<br/>
+
+To make Git “aware” of the `add`<swm-token data-swm-token=":git.c:485:4:4:`	{ &quot;add&quot;, cmd_add, RUN_SETUP | NEED_WORK_TREE },`"/> command, it needs to be registered by adding a `cmd_struct`<swm-token data-swm-token=":git.c:484:4:4:`static struct cmd_struct commands[] = {`"/> to the `commands`<swm-token data-swm-token=":git.c:484:6:6:`static struct cmd_struct commands[] = {`"/> array:
+<!-- NOTE-swimm-snippet: the lines below link your snippet to Swimm -->
+### 📄 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 },
+```
+
+<br/>
+
+This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/vvxtv).

.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 ([email protected]) 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.
+
+<br/>
+
+This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/p7eqt).

.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`<swm-token data-swm-token=":usage.c:295:4:4:`NORETURN void BUG(const char *fmt, ...)`"/>, `die`<swm-token data-swm-token=":usage.c:160:4:4:`void NORETURN die(const char *err, ...)`"/>, `usage`<swm-token data-swm-token=":usage.c:155:4:4:`void NORETURN usage(const char *err)`"/>, `error`<swm-token data-swm-token=":usage.c:227:2:2:`int error(const char *err, ...)`"/>, and `warning`<swm-token data-swm-token=":usage.c:247:2:2:`void warning(const char *warn, ...)`"/> 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`<swm-token data-swm-token=":parse-options.c:1002:4:4:`void NORETURN usage_with_options(const char * const *usagestr,`"/>)
+
+\- `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.
+
+<br/>
+
+## 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`.
+
+<br/>
+
+<br/>
+
+For example, "git daemon" uses `set_die_routine`<swm-token data-swm-token=":daemon.c:1436:1:1:`		set_die_routine(daemon_die);`"/> to write the reason `die`<swm-token data-swm-token=":usage.c:160:4:4:`void NORETURN die(const char *err, ...)`"/> was called to syslog before exiting.
+<!-- NOTE-swimm-snippet: the lines below link your snippet to Swimm -->
+### 📄 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
+```
+
+<br/>
+
+# Caller-handled errors
+
+An increasing number of functions take a parameter `struct strbuf *err`.
+
+<br/>
+
+<br/>
+
+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:
+<!-- NOTE-swimm-snippet: the lines below link your snippet to Swimm -->
+### 📄 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);
+```
+
+<br/>
+
+<br/>
+
+<br/>
+
+The 'err' parameter will be untouched if no error occurred, so multiple function calls can be chained:
+<!-- NOTE-swimm-snippet: the lines below link your snippet to Swimm -->
+### 📄 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);
+```
+
+<br/>
+
+<br/>
+
+<br/>
+
+<br/>
+
+This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/i3r5y).

.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`.
+
+<br/>
+
+This file was generated by Swimm. [Click here to view it in the app](https://app.swimm.io/repos/Z2l0aHViJTNBJTNBZ2l0LXNyYy1wbGF5Z3JvdW5kJTNBJTNBT21lclJvc2VuYmF1bQ==/docs/evxx4).