{"thread":{"id":"55934","subject":"[PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","startedAt":"2021-06-15T16:18:31Z","lastAt":"2021-06-17T20:57:53Z","messageCount":24,"participants":["Ævar Arnfjörð Bjarmason","Robert P. J. Day","Felipe Contreras","Junio C Hamano","Bagas Sanjaya","Jeff King","Randall S. Becker","Phillip Susi"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"427489","messageId":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":null,"subject":"[PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:17:57Z","receivedAt":"2021-06-15T16:18:31Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"I suggested in [1] that the \"alice\" and \"bob\" examples in our\ndocumentation would be better written without a reference to such\nfictional characters, for reasons that have nothing to do with trying\nto bend over backwards to avoid any reference to people's gender. It\njust makes for better documentation.\n\nSince it's clear that Derrick's not interested in picking up that task\nin his parallel series[2] here a brief series to implement that. This\nleaves the only occurances of \"alice\" and \"bob\" (and \"david\" and\n\"cindy\") at the bottom of giteveryday(7). Those could also be changed,\nbut I didn't think doing so provided a clear benefit, unlike the\nchanges being made here.\n\n1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/\n2. pull.975.v3.git.1623766273.gitgitgadget@gmail.com\n\nÆvar Arnfjörð Bjarmason (6):\n  gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"\n  gitcvs-migration doc: replace \"alice\" and \"bob\" with \"you\" and\n    \"www-data\"\n  daemon doc + code comments: reword \"alice\" example\n  fast-import doc: change \"bob\" in an example to \"file.txt\"\n  doc: replace \"alice\" and \"bob\" with \"jdoe\" and \"msmith\"\n  pack-protocol doc: use \"www-data\" in place of \"alice\"\n\n Documentation/git-credential.txt          |   2 +-\n Documentation/git-daemon.txt              |  13 ++-\n Documentation/git-fast-import.txt         |  14 ++-\n Documentation/git-imap-send.txt           |   4 +-\n Documentation/git-interpret-trailers.txt  |  22 ++--\n Documentation/gitcvs-migration.txt        |  18 +--\n Documentation/gittutorial.txt             | 128 +++++++++++-----------\n Documentation/technical/pack-protocol.txt |   4 +-\n daemon.c                                  |  10 +-\n 9 files changed, 112 insertions(+), 103 deletions(-)\n\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427490","messageId":"patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 1/6] gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:17:58Z","receivedAt":"2021-06-15T16:18:52Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rephrase the tutorial text added in 927a503cd07 (New tutorial,\n2006-01-22) to talk about a repository \"you\" have, and which you'd\nlike to deploy a local copy of to a \"www-data\" user, and what it'll\ntake to pull and push changes between the two.\n\nThere's been some parallel work to get rid of gendered language in the\nGit documentation[1] which has suggested that examples of \"Alice and\nBob\" should be excluded, as they're commonly used examples in\ntechnical documentation, especially documentation that deals with\ncryptography.\n\nI don't think such an example is problematic per-se, and it certainly\nhas its place. But if all we're trying to achieve is a generic example\nof pushing and pulling between two UIDs on the same (or different)\nmachine(s) it's needlessly verbose, especially to a reader who's not\nin the know about the meaning of the names in crypto documentation (I\ndaresay that's the vast majority of our users, especially those\nreading the tutorial).\n\nTo those in the know it's needlessly distracting. I for one tend do\nread such documentation half-distracted as I try to remember what the\nparticular implicit meaning of that cast of characters is (if any). Is\nthere going to be an \"Eve\" at some point who'll serve as a stand-in\nfor the eavesdropper[2]?\n\nIn this case the answer is \"no\"; so let's replace the whole thing with\na less verbose and I think more common example of wanting to deploy a\nrepository in /home to some other user (the most common of which is\nprobably this www-data example), and pulling and pushing between the\ntwo.\n\nThis commit also fixes the related issue of referring to an\n\"alice.org\" domain, we really should use the RFC 2606 domain names\ninstead of potentially being a cause of spam to innocent bystander's\nE-Mail addresses.\n\n1. http://lore.kernel.org/git/f06092a9053e40d93c4ec94b7fbbb1b8d563957b.1623766273.git.gitgitgadget@gmail.com\n2. https://en.wikipedia.org/wiki/Alice_and_Bob#Cast_of_characters\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/gittutorial.txt | 128 +++++++++++++++++-----------------\n 1 file changed, 63 insertions(+), 65 deletions(-)\n\ndiff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt\nindex 59ef5cef1f0..7848888b40b 100644\n--- a/Documentation/gittutorial.txt\n+++ b/Documentation/gittutorial.txt\n@@ -280,79 +280,79 @@ out.\n Using Git for collaboration\n ---------------------------\n \n-Suppose that Alice has started a new project with a Git repository in\n-/home/alice/project, and that Bob, who has a home directory on the\n-same machine, wants to contribute.\n+Suppose that you've started a new project with a Git repository in\n+/home/you/project, and you'd like another user on the same local\n+machine to be able to contribute to it. E.g. a www-data user to serve\n+the content up with a webserver.\n \n-Bob begins with:\n+As the `www-data` user do:\n \n ------------------------------------------------\n-bob$ git clone /home/alice/project myrepo\n+www-data$ git clone /home/you/project /var/www-data/deployment\n ------------------------------------------------\n \n-This creates a new directory \"myrepo\" containing a clone of Alice's\n+This creates a new directory \"deployment\" containing a clone of your\n repository.  The clone is on an equal footing with the original\n project, possessing its own copy of the original project's history.\n \n-Bob then makes some changes and commits them:\n+As `www-data` you then makes some changes and commit them:\n \n ------------------------------------------------\n (edit files)\n-bob$ git commit -a\n+www-data$ git commit -a\n (repeat as necessary)\n ------------------------------------------------\n \n-When he's ready, he tells Alice to pull changes from the repository\n-at /home/bob/myrepo.  She does this with:\n+You can then pull those changes to the checkout in your home directory\n+at /home/you/project:\n \n ------------------------------------------------\n-alice$ cd /home/alice/project\n-alice$ git pull /home/bob/myrepo master\n+you$ cd /home/you/project\n+you$ git pull /var/www-data/deployment master\n ------------------------------------------------\n \n-This merges the changes from Bob's \"master\" branch into Alice's\n-current branch.  If Alice has made her own changes in the meantime,\n-then she may need to manually fix any conflicts.\n+This merges the changes from the deployment repo's \"master\" branch into your\n+current branch.  If you've made other changes there in the meantime,\n+you may need to manually fix any conflicts.\n \n The \"pull\" command thus performs two operations: it fetches changes\n from a remote branch, then merges them into the current branch.\n \n-Note that in general, Alice would want her local changes committed before\n-initiating this \"pull\".  If Bob's work conflicts with what Alice did since\n-their histories forked, Alice will use her working tree and the index to\n+In general you'd want changes in your home directory to be committed before\n+initiating this \"pull\".  If your www-data work conflicts with them you\n+can use your working tree and the index to\n resolve conflicts, and existing local changes will interfere with the\n conflict resolution process (Git will still perform the fetch but will\n-refuse to merge --- Alice will have to get rid of her local changes in\n+refuse to merge --- You'll have to get rid of your local changes in\n some way and pull again when this happens).\n \n-Alice can peek at what Bob did without merging first, using the \"fetch\"\n-command; this allows Alice to inspect what Bob did, using a special\n-symbol \"FETCH_HEAD\", in order to determine if he has anything worth\n+You can look at those changes merging first, using the \"fetch\"\n+command; this allows you to inspect the remote state, using a special\n+symbol \"FETCH_HEAD\", in order to determine if there's anything worth\n pulling, like this:\n \n ------------------------------------------------\n-alice$ git fetch /home/bob/myrepo master\n-alice$ git log -p HEAD..FETCH_HEAD\n+$ git fetch /var/www-data/deployment master\n+you$ git log -p HEAD..FETCH_HEAD\n ------------------------------------------------\n \n-This operation is safe even if Alice has uncommitted local changes.\n+This operation is safe even if you've got uncommitted local changes.\n The range notation \"HEAD..FETCH_HEAD\" means \"show everything that is reachable\n from the FETCH_HEAD but exclude anything that is reachable from HEAD\".\n-Alice already knows everything that leads to her current state (HEAD),\n-and reviews what Bob has in his state (FETCH_HEAD) that she has not\n-seen with this command.\n+You know about everything that leads to your current state (HEAD),\n+and can review the state of the www-data repoistory (FETCH_HEAD).\n \n-If Alice wants to visualize what Bob did since their histories forked\n-she can issue the following command:\n+If you want to visualize that difference\n+you can issue the following command:\n \n ------------------------------------------------\n $ gitk HEAD..FETCH_HEAD\n ------------------------------------------------\n \n-This uses the same two-dot range notation we saw earlier with 'git log'.\n+This uses the same two-dot range notation that 'git log' does.\n \n-Alice may want to view what both of them did since they forked.\n-She can use three-dot form instead of the two-dot form:\n+To see commits from both repositories did since they forked.\n+use three-dot form instead of the two-dot form:\n \n ------------------------------------------------\n $ gitk HEAD...FETCH_HEAD\n@@ -364,11 +364,11 @@ exclude anything that is reachable from both of them\".\n Please note that these range notation can be used with both gitk\n and \"git log\".\n \n-After inspecting what Bob did, if there is nothing urgent, Alice may\n-decide to continue working without pulling from Bob.  If Bob's history\n-does have something Alice would immediately need, Alice may choose to\n-stash her work-in-progress first, do a \"pull\", and then finally unstash\n-her work-in-progress on top of the resulting history.\n+After inspecting the difference you may\n+decide to continue working without pulling from www-data.  If that history\n+does have something you need you can\n+stash your work-in-progress first, do a \"pull\", and then finally unstash\n+it on top of the resulting history.\n \n When you are working in a small closely knit group, it is not\n unusual to interact with the same repository over and over\n@@ -376,79 +376,77 @@ again.  By defining 'remote' repository shorthand, you can make\n it easier:\n \n ------------------------------------------------\n-alice$ git remote add bob /home/bob/myrepo\n+you$ git remote add deployment /var/www-data/deployment\n ------------------------------------------------\n \n-With this, Alice can perform the first part of the \"pull\" operation\n-alone using the 'git fetch' command without merging them with her own\n-branch, using:\n+With this, you can use the \"deployment\" name for that remote\n+as an argument to 'git pull' or 'git fetch':\n \n -------------------------------------\n-alice$ git fetch bob\n+you$ git fetch deployment\n -------------------------------------\n \n-Unlike the longhand form, when Alice fetches from Bob using a\n+Unlike the longhand form, when you fetch using a\n remote repository shorthand set up with 'git remote', what was\n fetched is stored in a remote-tracking branch, in this case\n-`bob/master`.  So after this:\n+`deployment/master`.  So after this:\n \n -------------------------------------\n-alice$ git log -p master..bob/master\n+you$ git log -p master..deployment/master\n -------------------------------------\n \n-shows a list of all the changes that Bob made since he branched from\n-Alice's master branch.\n+shows a list of all the changes in deployment/master since it branched\n+off from your master branch.\n \n-After examining those changes, Alice\n-could merge the changes into her master branch:\n+After examining those changes, you can merge them into your master branch:\n \n -------------------------------------\n-alice$ git merge bob/master\n+you$ git merge deployment/master\n -------------------------------------\n \n-This `merge` can also be done by 'pulling from her own remote-tracking\n-branch', like this:\n+This `merge` can also be done by 'pulling from the remote-tracking\n+branch':\n \n -------------------------------------\n-alice$ git pull . remotes/bob/master\n+you$ git pull . remotes/deployment/master\n -------------------------------------\n \n Note that git pull always merges into the current branch,\n regardless of what else is given on the command line.\n \n-Later, Bob can update his repo with Alice's latest changes using\n+Later, the www-data clone can be updated with your latest changes using\n \n -------------------------------------\n-bob$ git pull\n+www-data$ git pull\n -------------------------------------\n \n-Note that he doesn't need to give the path to Alice's repository;\n-when Bob cloned Alice's repository, Git stored the location of her\n-repository in the repository configuration, and that location is\n+Note that you don't need to supply the path to the original repository;\n+when you cloned it the path was stored in\n+the repository configuration, and that location is\n used for pulls:\n \n -------------------------------------\n-bob$ git config --get remote.origin.url\n-/home/alice/project\n+www-data$ git config --get remote.origin.url\n+/home/you/project\n -------------------------------------\n \n (The complete configuration created by 'git clone' is visible using\n `git config -l`, and the linkgit:git-config[1] man page\n explains the meaning of each option.)\n \n-Git also keeps a pristine copy of Alice's master branch under the\n+That cloned repository also keeps a copy of its remote master branch under the\n name \"origin/master\":\n \n -------------------------------------\n-bob$ git branch -r\n+www-data$ git branch -r\n   origin/master\n -------------------------------------\n \n-If Bob later decides to work from a different host, he can still\n+If you decide to move that deployment clone to a diffeent host, you can still\n perform clones and pulls using the ssh protocol:\n \n -------------------------------------\n-bob$ git clone alice.org:/home/alice/project myrepo\n+www-data$ git clone you.example.org:/home/you/project myrepo\n -------------------------------------\n \n Alternatively, Git has a native protocol, or can use http;\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427491","messageId":"patch-2.6-39e8654507c-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 2/6] gitcvs-migration doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:17:59Z","receivedAt":"2021-06-15T16:18:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Continue the work started in the last commit and change the cast of\ncharacters introduced in cd976f5c526 (Documentation: reorganize\ncvs-migration.txt, 2006-12-06) to refer to the \"you\" and \"www-data\"\nexamples the gittutorial documentation now uses.\n\nIn addition to the reasons for this in the last commit, this also\nbrings the gitcvs-migration documentation in line with the example in\nthe tutorial, which was added by the same author at a around the same\ntime in 927a503cd07 (New tutorial, 2006-01-22).\n\nAside from talking about a bare repository here and a non-bare\ncheckout in the tutorial we use the same paths, and make explicit\nreference to the more extended documentation in the tutorial here and\nits relevance to this example.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/gitcvs-migration.txt | 18 +++++++++++-------\n 1 file changed, 11 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt\nindex 1cd1283d0f8..f2ff379886e 100644\n--- a/Documentation/gitcvs-migration.txt\n+++ b/Documentation/gitcvs-migration.txt\n@@ -86,17 +86,21 @@ possibly created from scratch or from a tarball (see\n linkgit:gittutorial[7]), or imported from an already existing CVS\n repository (see the next section).\n \n-Assume your existing repo is at /home/alice/myproject.  Create a new \"bare\"\n-repository (a repository without a working tree) and fetch your project into\n-it:\n+Assume your existing repo is at /home/you/project.  Create a new \"bare\"\n+repository (a repository withoupt a working tree) and fetch your project into\n+it. \n \n ------------------------------------------------\n-$ mkdir /pub/my-repo.git\n-$ cd /pub/my-repo.git\n+$ mkdir /var/www-data/deployment.git\n+$ cd /var/www-data/deployment.git\n $ git --bare init --shared\n-$ git --bare fetch /home/alice/myproject master:master\n+$ git --bare fetch /home/you/project master:master\n ------------------------------------------------\n \n+(See the \"Using Git for collaboration\" section in\n+linkgit:gittutorial[7] for an extended version of this example that\n+doesn't use a bare repository.)\n+\n Next, give every team member read/write access to this repository.  One\n easy way to do this is to give all the team members ssh access to the\n machine where the repository is hosted.  If you don't want to give them a\n@@ -107,7 +111,7 @@ Put all the committers in the same group, and make the repository\n writable by that group:\n \n ------------------------------------------------\n-$ chgrp -R $group /pub/my-repo.git\n+$ chgrp -R $group /var/www-data/deployment.git\n ------------------------------------------------\n \n Make sure committers have a umask of at most 027, so that the directories\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427492","messageId":"patch-3.6-30cffc12410-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 3/6] daemon doc + code comments: reword \"alice\" example","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:18:00Z","receivedAt":"2021-06-15T16:19:08Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Improve on the \"alice\" example added in 603968d22b1 (daemon: extend\nuser-relative path notation., 2006-02-04). I found the previous\nversion of this documentation a bit confusing, and had to read the\ncode to see what it was doing.\n\nI think explicitly spelling out that the --user-path option can be\nuser to provide an infix to stash in-between what we'll resolve\n\"~user\" and the path after that is clearer, especially when coupled\nwith explicit examples of path resolution.\n\nFinally, the previous documentation didn't mention that `path/foo`\ncould actually resolve to `path/foo.git`. That's implicitly covered\nearlier in the documentation, let's make an explicit reference to that\nhere.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-daemon.txt | 13 ++++++++-----\n daemon.c                     | 10 +++++-----\n 2 files changed, 13 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex fdc28c041c7..a109189756d 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -139,11 +139,14 @@ otherwise `stderr`.\n --user-path=<path>::\n \tAllow {tilde}user notation to be used in requests.  When\n \tspecified with no parameter, requests to\n-\tgit://host/{tilde}alice/foo is taken as a request to access\n-\t'foo' repository in the home directory of user `alice`.\n-\tIf `--user-path=path` is specified, the same request is\n-\ttaken as a request to access `path/foo` repository in\n-\tthe home directory of user `alice`.\n+\tgit://host/{tilde}user/foo is taken as a request to access\n+\t'foo' repository in the home directory of user `user`.\n++\n+If `--user-path=infix` is specified, the `infix` is appended to the path\n+found with the {tilde}user notation. E.g. a request to access a `some/foo`\n+repository (git://host/{tilde}user/some/foo) will resolve to (assuming that\n+`$HOME` is `/home`) either `/home/user/infix/some/foo` (or `[...]/foo.git`\n+etc., see `--strict-paths` above).\n \n --verbose::\n \tLog details about the incoming connections and requested files.\ndiff --git a/daemon.c b/daemon.c\nindex 5c4cbad62d0..a939e5ee0e0 100644\n--- a/daemon.c\n+++ b/daemon.c\n@@ -46,8 +46,8 @@ static const char *interpolated_path;\n static int base_path_relaxed;\n \n /* If defined, ~user notation is allowed and the string is inserted\n- * after ~user/.  E.g. a request to git://host/~alice/frotz would\n- * go to /home/alice/pub_git/frotz with --user-path=pub_git.\n+ * after ~user/.  E.g. a request to git://host/~user/frotz would\n+ * go to /home/user/pub_git/frotz with --user-path=pub_git.\n  */\n static const char *user_path;\n \n@@ -188,9 +188,9 @@ static const char *path_ok(const char *directory, struct hostinfo *hi)\n \t\t\treturn NULL;\n \t\t}\n \t\tif (*user_path) {\n-\t\t\t/* Got either \"~alice\" or \"~alice/foo\";\n-\t\t\t * rewrite them to \"~alice/%s\" or\n-\t\t\t * \"~alice/%s/foo\".\n+\t\t\t/* Got either \"~user\" or \"~user/foo\";\n+\t\t\t * rewrite them to \"~user/%s\" or\n+\t\t\t * \"~user/%s/foo\".\n \t\t\t */\n \t\t\tint namlen, restlen = strlen(dir);\n \t\t\tconst char *slash = strchr(dir, '/');\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427493","messageId":"patch-4.6-0b464dc51d8-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 4/6] fast-import doc: change \"bob\" in an example to \"file.txt\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:18:01Z","receivedAt":"2021-06-15T16:19:11Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The example added in e7e5170f804 (Update fast-import documentation to\ndiscuss crash reports, 2008-02-14) is a bit confusing in that we're\nreferring to a \"bob\" when we really just need a placeholder name for a\nfile that has bad mode bits, let's use \"file.txt\" instead.\n\nLet's also use \"<<-\" in the here-doc so this'll work if the reader\ncopies this from e.g. a tab-indented manual page, none of the content\nneeds leading whitespace, so that won't break anything if the content\nisn't indented.\n\nThe fast-import error message and other output has also changed\nslightly since 2008, let's update the relevant parts of it, while\nretaining the original PID, time etc. of the 2007-era example.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-fast-import.txt | 14 +++++++++-----\n 1 file changed, 9 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 39cfa05b28b..ddaa8e5d755 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -1277,7 +1277,7 @@ must be applied manually if the update is needed.\n An example crash:\n \n ====\n-\t$ cat >in <<END_OF_INPUT\n+\t$ cat >in <<-END_OF_INPUT\n \t# my very first test commit\n \tcommit refs/heads/master\n \tcommitter Shawn O. Pearce <spearce> 19283 -0400\n@@ -1289,12 +1289,13 @@ An example crash:\n \tdata <<EOF\n \t.gitignore\n \tEOF\n-\tM 777 inline bob\n+\tM 777 inline file.txt\n \tEND_OF_INPUT\n \n \t$ git fast-import <in\n-\tfatal: Corrupt mode: M 777 inline bob\n+\tfatal: Corrupt mode: M 777 inline file.txt\n \tfast-import: dumping crash report to .git/fast_import_crash_8434\n+\tUnpacking objects: 100% (1/1), 32 bytes | 32.00 KiB/s, done.\n \n \t$ cat .git/fast_import_crash_8434\n \tfast-import crash report:\n@@ -1302,7 +1303,7 @@ An example crash:\n \t    parent process     : 1391\n \t    at Sat Sep 1 00:58:12 2007\n \n-\tfatal: Corrupt mode: M 777 inline bob\n+\tfatal: Corrupt mode: M 777 inline file.txt\n \n \tMost Recent Commands Before Crash\n \t---------------------------------\n@@ -1313,7 +1314,7 @@ An example crash:\n \t  data <<EOF\n \t  M 644 inline .gitignore\n \t  data <<EOF\n-\t* M 777 inline bob\n+\t* M 777 inline file.txt\n \n \tActive Branch LRU\n \t-----------------\n@@ -1334,6 +1335,9 @@ An example crash:\n \t  last pack   :\n \n \n+\tMarks\n+\t-----\n+\n \t-------------------\n \tEND OF CRASH REPORT\n ====\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427494","messageId":"patch-5.6-65b7123e701-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 5/6] doc: replace \"alice\" and \"bob\" with \"jdoe\" and \"msmith\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:18:02Z","receivedAt":"2021-06-15T16:19:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the \"Alice\" and \"Bob\" generic example users to jdoe@example.com\nand msmith@example.com.\n\nThe former is widely used in RFC 5322 as an example E-Mail address,\nthe latter is not, but \"Mary Smith <mary@example.com>\". It has been\nclaimed that any reference to people's gender in our documentation is\ndistracting to some readers[1]. In this case it's easy enough to tweak\nthe example in such a way that the reader can insert their own\nstand-in for \"M.\".\n\n1. https://lore.kernel.org/git/pull.975.v3.git.1623766273.gitgitgadget@gmail.com/\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-credential.txt         |  2 +-\n Documentation/git-imap-send.txt          |  4 ++--\n Documentation/git-interpret-trailers.txt | 22 +++++++++++-----------\n 3 files changed, 14 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 206e3c5f407..86b4c32affa 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -69,7 +69,7 @@ information it has):\n \n \tprotocol=https\n \thost=example.com\n-\tusername=bob\n+\tusername=jdoe\n \tpassword=secr3t\n +\n In most cases, this means the attributes given in the input will be\ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex 63cf498ce9f..902f0e8ed34 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -72,7 +72,7 @@ Using direct mode:\n [imap]\n     folder = \"INBOX.Drafts\"\n     host = imap://imap.example.com\n-    user = bob\n+    user = jdoe\n     pass = p4ssw0rd\n .........................\n \n@@ -82,7 +82,7 @@ Using direct mode with SSL:\n [imap]\n     folder = \"INBOX.Drafts\"\n     host = imaps://imap.example.com\n-    user = bob\n+    user = jdoe\n     pass = p4ssw0rd\n     port = 123\n     ; sslVerify = false\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 956a01d184f..17a19960ba3 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -277,13 +277,13 @@ $ cat msg.txt\n subject\n \n message\n-$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'\n+$ cat msg.txt | git interpret-trailers --trailer 'sign: J. Doe <jdoe@example.com>' --trailer 'sign: M. Smith <msmith@example.com>'\n subject\n \n message\n \n-Signed-off-by: Alice <alice@example.com>\n-Signed-off-by: Bob <bob@example.com>\n+Signed-off-by: J. Doe <jdoe@example.com>\n+Signed-off-by: M. Smith <msmith@example.com>\n ------------\n \n * Use the `--in-place` option to edit a message file in place:\n@@ -294,15 +294,15 @@ subject\n \n message\n \n-Signed-off-by: Bob <bob@example.com>\n-$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt\n+Signed-off-by: M. Smith <msmith@example.com>\n+$ git interpret-trailers --trailer 'Acked-by: J. Doe <jdoe@example.com>' --in-place msg.txt\n $ cat msg.txt\n subject\n \n message\n \n-Signed-off-by: Bob <bob@example.com>\n-Acked-by: Alice <alice@example.com>\n+Signed-off-by: M. Smith <msmith@example.com>\n+Acked-by: J. Doe <jdoe@example.com>\n ------------\n \n * Extract the last commit as a patch, and add a 'Cc' and a\n@@ -311,7 +311,7 @@ Acked-by: Alice <alice@example.com>\n ------------\n $ git format-patch -1\n 0001-foo.patch\n-$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch\n+$ git interpret-trailers --trailer 'Cc: J. Doe <jdoe@example.com>' --trailer 'Reviewed-by: M. Smith <msmith@example.com>' 0001-foo.patch >0001-bar.patch\n ------------\n \n * Configure a 'sign' trailer with a command to automatically add a\n@@ -326,12 +326,12 @@ $ git config trailer.sign.command 'echo \"$(git config user.name) <$(git config u\n $ git interpret-trailers <<EOF\n > EOF\n \n-Signed-off-by: Bob <bob@example.com>\n+Signed-off-by: M. Smith <msmith@example.com>\n $ git interpret-trailers <<EOF\n-> Signed-off-by: Alice <alice@example.com>\n+> Signed-off-by: J. Doe <jdoe@example.com>\n > EOF\n \n-Signed-off-by: Alice <alice@example.com>\n+Signed-off-by: J. Doe <jdoe@example.com>\n ------------\n \n * Configure a 'fix' trailer with a key that contains a '#' and no\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427495","messageId":"patch-6.6-9c4a7545cb7-20210615T161330Z-avarab@gmail.com","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"[PATCH 6/6] pack-protocol doc: use \"www-data\" in place of \"alice\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T16:18:03Z","receivedAt":"2021-06-15T16:19:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Replace the example of \"alice\" in the pack-protocol.txt documentation\nadded in b31222cfb7f (Update packfile transfer protocol documentation,\n2009-11-03) with \"www-data\". This is now consistent with the recently\nchanged examples in the tutorial and git-daemon documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/technical/pack-protocol.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt\nindex e13a2c064d1..0f43a290e59 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/technical/pack-protocol.txt\n@@ -136,10 +136,10 @@ directory, because the Git client will run:\n The exception is if a '~' is used, in which case\n we execute it without the leading '/'.\n \n-      ssh://user@example.com/~alice/project.git,\n+      ssh://user@example.com/~www-data/project.git,\n \t\t     |\n \t\t     v\n-   ssh user@example.com \"git-upload-pack '~alice/project.git'\"\n+   ssh user@example.com \"git-upload-pack '~www-data/project.git'\"\n \n Depending on the value of the `protocol.version` configuration variable,\n Git may attempt to send Extra Parameters as a colon-separated string in\n-- \n2.32.0.555.g0268d380f7b\n\n"},{"id":"427501","messageId":"18b53cae-6da9-c970-b994-caee11c5baf9@crashcourse.ca","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2021-06-15T16:46:47Z","receivedAt":"2021-06-15T16:46:56Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Tue, 15 Jun 2021, Ævar Arnfjörð Bjarmason wrote:\n\n> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> documentation would be better written without a reference to such\n> fictional characters, for reasons that have nothing to do with trying\n> to bend over backwards to avoid any reference to people's gender. It\n> just makes for better documentation.\n\n  no, it doesn't ... and wikipedia explains it nicely:\n\nhttps://en.wikipedia.org/wiki/Alice_and_Bob\n\n\"In cryptography, Alice and Bob are fictional characters commonly used\nas placeholders in discussions about cryptographic protocols or\nsystems, and in other science and engineering literature where there\nare several participants in a thought experiment. The Alice and Bob\ncharacters were invented by Ron Rivest, Adi Shamir, and Leonard\nAdleman in their 1978 paper \"A Method for Obtaining Digital Signatures\nand Public-key Cryptosystems\".[1] Subsequently, they have become\ncommon archetypes in many scientific and engineering fields, such as\nquantum cryptography, game theory and physics.[2] As the use of Alice\nand Bob became more widespread, additional characters were added,\nsometimes each with a particular meaning. These characters do not have\nto refer to humans; they refer to generic agents which might be\ndifferent computers or even different programs running on a single\ncomputer.\"\n\n  if you want to make the docs better, have at it, but please don't do\nsomething as meaningless as replacing \"bob\" and \"alice\" because you're\nfeeling politically correct, or woke, or whatever the hell the kids\ncall it these days.\n\n  jesus ...\n\nrday"},{"id":"427503","messageId":"60c8db3558fb8_1296f208ac@natae.notmuch","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"RE: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-15T16:54:13Z","receivedAt":"2021-06-15T16:54:17Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> documentation would be better written without a reference to such\n> fictional characters, for reasons that have nothing to do with trying\n> to bend over backwards to avoid any reference to people's gender. It\n> just makes for better documentation.\n\nI'm fond of Alice and Bob, and I'm saddened they are the latest casualty\nof the culture war, but if we are avoiding gender of examples, it makes\nsense to let them go.\n\nHowever, I want to defend this usage a little.\n\n  1. Alice and Bob are familiar, so it requires less cogntive load from\n     the user.\n  2. Alice and Bob promote the usage of git as a distributed VCS, where\n     unlike centralized VCS, you directly use the repositories of your\n     colleagues.\n  3. They provide some relief to an otherwise sterile landscape.\n\nI don't think these changes make for a necessarily better documentation,\njust a more sterile one.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"427520","messageId":"874kdzymzh.fsf@evledraar.gmail.com","threadId":"55934","inReplyTo":"18b53cae-6da9-c970-b994-caee11c5baf9@crashcourse.ca","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T18:45:33Z","receivedAt":"2021-06-15T18:57:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Jun 15 2021, Robert P. J. Day wrote:\n\n> On Tue, 15 Jun 2021, Ævar Arnfjörð Bjarmason wrote:\n>\n>> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n>> documentation would be better written without a reference to such\n>> fictional characters, for reasons that have nothing to do with trying\n>> to bend over backwards to avoid any reference to people's gender. It\n>> just makes for better documentation.\n>\n>   no, it doesn't ... and wikipedia explains it nicely:\n\nIt doesn't make for better documentation? Maybe not, but can you comment\non specific parts of the changes in this series that make it worse?\n\n> https://en.wikipedia.org/wiki/Alice_and_Bob\n>\n> \"In cryptography, Alice and Bob are fictional characters commonly used\n> as placeholders in discussions about cryptographic protocols or\n> systems, and in other science and engineering literature where there\n> are several participants in a thought experiment. The Alice and Bob\n> characters were invented by Ron Rivest, Adi Shamir, and Leonard\n> Adleman in their 1978 paper \"A Method for Obtaining Digital Signatures\n> and Public-key Cryptosystems\".[1] Subsequently, they have become\n> common archetypes in many scientific and engineering fields, such as\n> quantum cryptography, game theory and physics.[2] As the use of Alice\n> and Bob became more widespread, additional characters were added,\n> sometimes each with a particular meaning. These characters do not have\n> to refer to humans; they refer to generic agents which might be\n> different computers or even different programs running on a single\n> computer.\"\n>\n>   if you want to make the docs better, have at it, but please don't do\n> something as meaningless as replacing \"bob\" and \"alice\" because you're\n> feeling politically correct, or woke, or whatever the hell the kids\n> call it these days.\n>\n>   jesus ...\n\nI believe that the commit message of 1/6 addresses the point you're\nraising here:\nhttp://lore.kernel.org/git/patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com\n"},{"id":"427521","messageId":"871r93ym8q.fsf@evledraar.gmail.com","threadId":"55934","inReplyTo":"60c8db3558fb8_1296f208ac@natae.notmuch","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-15T19:09:13Z","receivedAt":"2021-06-15T19:13:46Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, Jun 15 2021, Felipe Contreras wrote:\n\n> Ævar Arnfjörð Bjarmason wrote:\n>> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n>> documentation would be better written without a reference to such\n>> fictional characters, for reasons that have nothing to do with trying\n>> to bend over backwards to avoid any reference to people's gender. It\n>> just makes for better documentation.\n>\n> I'm fond of Alice and Bob, and I'm saddened they are the latest casualty\n> of the culture war, but if we are avoiding gender of examples, it makes\n> sense to let them go.\n>\n> However, I want to defend this usage a little.\n>\n>   1. Alice and Bob are familiar, so it requires less cogntive load from\n>      the user.\n>   2. Alice and Bob promote the usage of git as a distributed VCS, where\n>      unlike centralized VCS, you directly use the repositories of your\n>      colleagues.\n>   3. They provide some relief to an otherwise sterile landscape.\n>\n> I don't think these changes make for a necessarily better documentation,\n> just a more sterile one.\n\nFair enough, for what it's worth I wouldn't recommend against using\nthese names in general, I would think you'd actively seek out those\nactors in e.g. cryptography documentation.\n\nBut as I argue in 1/6 I think these references go over the head of most\nof our users, and those users are better served by more succinct\ndocumentation.\n\nThe diffstat for the series as a whole increases line count, but it's\nbecause of e.g. 3/6 elaborating on the function of the --user-path\nswitch, in the case of 1/6 we've got a reduction in lines and number of\nwords.\n\nAnd as argued in 1/6 for those users who /are/ aware of \"Alice and Bob\"\nit's needless distraction. Maybe it's just me, but whenever I read\nreferences to them I keep waiting for the cryptography angle to be\nintroduced. None of the uses in our documentation reflect that canonical\nusage.\n\nThere's also just weird things in our documentation fixed by this\nseries, such as referring to a random file tracked by git as \"bob\"\ninstead of the more obvious \"file.txt\".\n"},{"id":"427564","messageId":"xmqqfsxitw2n.fsf@gitster.g","threadId":"55934","inReplyTo":"cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-16T01:52:32Z","receivedAt":"2021-06-16T01:52:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> documentation would be better written without a reference to such\n> fictional characters, for reasons that have nothing to do with trying\n> to bend over backwards to avoid any reference to people's gender. It\n> just makes for better documentation.\n\nI actually do not mind cast of characters with concrete names,\nespecially when there are more than three parties involved and\nhaving names for them help clarify the description.  But I agree\nwith you that Alice and Bob should be reserved for situations where\nappearance of Eve would reasonably be anticipated, or the use of\nthese two names become distracting to those who happen to be aware\nhow these characters are often used in CS literature.\n\nPerhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?\n"},{"id":"427570","messageId":"8250d8af-2d52-321c-36a7-d71c29fc1ef1@gmail.com","threadId":"55934","inReplyTo":"patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com","subject":"Re: [PATCH 1/6] gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-06-16T03:43:32Z","receivedAt":"2021-06-16T03:43:44Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 15/06/21 23.17, Ævar Arnfjörð Bjarmason wrote:\n> -Suppose that Alice has started a new project with a Git repository in\n> -/home/alice/project, and that Bob, who has a home directory on the\n> -same machine, wants to contribute.\n> +Suppose that you've started a new project with a Git repository in\n> +/home/you/project, and you'd like another user on the same local\n> +machine to be able to contribute to it. E.g. a www-data user to serve\n> +the content up with a webserver.\n>   \n> -Bob begins with:\n> +As the `www-data` user do:\n>    >   ------------------------------------------------\n> -bob$ git clone /home/alice/project myrepo\n> +www-data$ git clone /home/you/project /var/www-data/deployment\n>   ------------------------------------------------\n> \n\nThis assumes that we're on Debian or its derivatives, however many users \nrun Git on other distributions (Fedora, Arch, Gentoo, openSUSE, etc.), \nso `www-data` user may not be present there. Also, `www-data` is system \naccount, as opposed to normal user account, so you can't log in to it; \nyou need as root `chown -R www-data:www-data /somewhere/`.\n\nThis also assumes that we use Apache HTTPD. The setup for other \nwebservers may be different. For example, if NGINX is used (installed \nfrom upstream packages rather than from Debian package repository), you \nneed to make site root (the path specified in `root` directive) readable \nby `nginx` user.\n\n> -This creates a new directory \"myrepo\" containing a clone of Alice's\n> +This creates a new directory \"deployment\" containing a clone of your\n>   repository.  The clone is on an equal footing with the original\n>   project, possessing its own copy of the original project's history.\n>  \n\nBut the scenario is we're cloning from local repo, so `git clone` here \nimplies --local (and bypasses normal Git transport mechanism), so to get \nclone experience similar to when using remote repo, we can use \n--no-local instead.\n\n> -Bob then makes some changes and commits them:\n> +As `www-data` you then makes some changes and commit them:\n>   \n>   ------------------------------------------------\n>   (edit files)\n> -bob$ git commit -a\n> +www-data$ git commit -a\n>   (repeat as necessary)\n>   ------------------------------------------------\n>   \n> -When he's ready, he tells Alice to pull changes from the repository\n> -at /home/bob/myrepo.  She does this with:\n> +You can then pull those changes to the checkout in your home directory\n> +at /home/you/project:\n>   \n>   ------------------------------------------------\n> -alice$ cd /home/alice/project\n> -alice$ git pull /home/bob/myrepo master\n> +you$ cd /home/you/project\n> +you$ git pull /var/www-data/deployment master\n>   ------------------------------------------------\n>   \n\nThe resulting rewrite until this point makes no sense for me. Previously \nwe have Alice and Bob working the project, but now you do the same, one \nas normal user account and one as system user `www-data`. Honestly I \nwould like keeping the status quo.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"427571","messageId":"c67312d5-cc71-7337-6c14-56ecfbba7737@gmail.com","threadId":"55934","inReplyTo":"patch-2.6-39e8654507c-20210615T161330Z-avarab@gmail.com","subject":"Re: [PATCH 2/6] gitcvs-migration doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-06-16T04:02:13Z","receivedAt":"2021-06-16T04:02:27Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 15/06/21 23.17, Ævar Arnfjörð Bjarmason wrote:\n>   ------------------------------------------------\n> -$ mkdir /pub/my-repo.git\n> -$ cd /pub/my-repo.git\n> +$ mkdir /var/www-data/deployment.git\n> +$ cd /var/www-data/deployment.git\n>   $ git --bare init --shared\n> -$ git --bare fetch /home/alice/myproject master:master\n> +$ git --bare fetch /home/you/project master:master\n>   ------------------------------------------------\n>   \n\nNormally you need to mkdir there as root.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"427576","messageId":"xmqqfsxiqup7.fsf@gitster.g","threadId":"55934","inReplyTo":"8250d8af-2d52-321c-36a7-d71c29fc1ef1@gmail.com","subject":"Re: [PATCH 1/6] gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-16T04:50:28Z","receivedAt":"2021-06-16T04:50:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n>> +As the `www-data` user do:\n>>    >   ------------------------------------------------\n>> -bob$ git clone /home/alice/project myrepo\n>> +www-data$ git clone /home/you/project /var/www-data/deployment\n>>   ------------------------------------------------\n>> \n>\n> This assumes that we're on Debian or its derivatives, however many\n> users run Git on other distributions (Fedora, Arch, Gentoo, openSUSE,\n> etc.), so `www-data` user may not be present there. Also, `www-data`\n> is system account, as opposed to normal user account, so you can't log\n> in to it; you need as root `chown -R www-data:www-data /somewhere/`.\n>\n> This also assumes that we use Apache HTTPD. The setup for other\n> webservers may be different. For example, if NGINX is used (installed \n> from upstream packages rather than from Debian package repository),\n> you need to make site root (the path specified in `root` directive)\n> readable by `nginx` user.\n\nI do not see what is wrong with all of the above.\n\nIt is perfectly fine to assume that our readers are intelligent\nenough to be able to guess from the above command line example that\ncontents for some webserver's htdocs directory is being prepared,\nand the data is coming from /home/you/project repository.  It is not\na tutorial on \"how to configure your webserver and deploy directly\nto its htdocs\", so lack of webserver specific configuration details\nis _desirable_.\n\nHaving said all that, I still like my s/Alice/Tabby/; s/Bob/Fido/\nmechanical replacement better ;-)\n"},{"id":"427596","messageId":"9217211e-aa26-c1c9-2528-a29b93ff174e@crashcourse.ca","threadId":"55934","inReplyTo":"xmqqfsxitw2n.fsf@gitster.g","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2021-06-16T09:30:14Z","receivedAt":"2021-06-16T09:30:24Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Wed, 16 Jun 2021, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n> > I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> > documentation would be better written without a reference to such\n> > fictional characters, for reasons that have nothing to do with trying\n> > to bend over backwards to avoid any reference to people's gender. It\n> > just makes for better documentation.\n>\n> I actually do not mind cast of characters with concrete names,\n> especially when there are more than three parties involved and\n> having names for them help clarify the description.  But I agree\n> with you that Alice and Bob should be reserved for situations where\n> appearance of Eve would reasonably be anticipated, or the use of\n> these two names become distracting to those who happen to be aware\n> how these characters are often used in CS literature.\n>\n> Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?\n\n  i look forward to the renaming of \"git\" to something more innocuous\nand palatable because, somewhere, someone could conceivably,\nhypothetically, theoretically take exception to it.\n\n  seriously, can we start a second mailing list where people want to\ntalk about, you know, version control?\n\nrday"},{"id":"427605","messageId":"YMnn64zrMO1T1HTY@coredump.intra.peff.net","threadId":"55934","inReplyTo":"9217211e-aa26-c1c9-2528-a29b93ff174e@crashcourse.ca","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-06-16T12:00:43Z","receivedAt":"2021-06-16T12:00:47Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 16, 2021 at 05:30:14AM -0400, Robert P. J. Day wrote:\n\n> On Wed, 16 Jun 2021, Junio C Hamano wrote:\n> \n> > Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n> >\n> > > I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> > > documentation would be better written without a reference to such\n> > > fictional characters, for reasons that have nothing to do with trying\n> > > to bend over backwards to avoid any reference to people's gender. It\n> > > just makes for better documentation.\n> >\n> > I actually do not mind cast of characters with concrete names,\n> > especially when there are more than three parties involved and\n> > having names for them help clarify the description.  But I agree\n> > with you that Alice and Bob should be reserved for situations where\n> > appearance of Eve would reasonably be anticipated, or the use of\n> > these two names become distracting to those who happen to be aware\n> > how these characters are often used in CS literature.\n> >\n> > Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?\n> \n>   i look forward to the renaming of \"git\" to something more innocuous\n> and palatable because, somewhere, someone could conceivably,\n> hypothetically, theoretically take exception to it.\n> \n>   seriously, can we start a second mailing list where people want to\n> talk about, you know, version control?\n\nCan you please tone down your responses a bit?\n\nOne of the points under discussion here is whether those names end up\nbeing confusing to users because of their use in other places (like\ncryptographic examples). And I think the comprehensibility of our\ndocumentation is quite relevant to the project.\n\nBut even if this were done purely for reasons of gender-neutrality, I\nstill think your response is inappropriate. You are quite welcome to\nargue against such a change, but snarky or dismissive responses aren't\nwelcome.\n\n(I'm referring to the last paragraph of your other response in this\nthread, too. I did find the wikipedia link you sent earlier helpful to\nthe discussion, and personally I don't find the names confusing at all,\nfor the reasons it mentioned. But that may not be universal).\n\n-Peff\n"},{"id":"427633","messageId":"60ca6586607f5_602720852@natae.notmuch","threadId":"55934","inReplyTo":"871r93ym8q.fsf@evledraar.gmail.com","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-16T20:56:38Z","receivedAt":"2021-06-16T20:56:42Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> \n> On Tue, Jun 15 2021, Felipe Contreras wrote:\n> \n> > Ævar Arnfjörð Bjarmason wrote:\n> >> I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> >> documentation would be better written without a reference to such\n> >> fictional characters, for reasons that have nothing to do with trying\n> >> to bend over backwards to avoid any reference to people's gender. It\n> >> just makes for better documentation.\n> >\n> > I'm fond of Alice and Bob, and I'm saddened they are the latest casualty\n> > of the culture war, but if we are avoiding gender of examples, it makes\n> > sense to let them go.\n> >\n> > However, I want to defend this usage a little.\n> >\n> >   1. Alice and Bob are familiar, so it requires less cogntive load from\n> >      the user.\n> >   2. Alice and Bob promote the usage of git as a distributed VCS, where\n> >      unlike centralized VCS, you directly use the repositories of your\n> >      colleagues.\n> >   3. They provide some relief to an otherwise sterile landscape.\n> >\n> > I don't think these changes make for a necessarily better documentation,\n> > just a more sterile one.\n> \n> Fair enough, for what it's worth I wouldn't recommend against using\n> these names in general, I would think you'd actively seek out those\n> actors in e.g. cryptography documentation.\n\nI have not read cryptography documentation, so for me Alice and Bob are\nsimply two illustrative colleagues.\n\n> And as argued in 1/6 for those users who /are/ aware of \"Alice and Bob\"\n> it's needless distraction. Maybe it's just me, but whenever I read\n> references to them I keep waiting for the cryptography angle to be\n> introduced. None of the uses in our documentation reflect that canonical\n> usage.\n\nIt's probably not just you, but the vast majority of readers are\nlikely not aware of any cryptographic reference.\n\n> There's also just weird things in our documentation fixed by this\n> series, such as referring to a random file tracked by git as \"bob\"\n> instead of the more obvious \"file.txt\".\n\nOK, _that_ I agree it's unequivocally an improvement.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"427634","messageId":"60ca66304a0a0_6027208c8@natae.notmuch","threadId":"55934","inReplyTo":"xmqqfsxitw2n.fsf@gitster.g","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-16T20:59:28Z","receivedAt":"2021-06-16T20:59:33Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n> \n> > I suggested in [1] that the \"alice\" and \"bob\" examples in our\n> > documentation would be better written without a reference to such\n> > fictional characters, for reasons that have nothing to do with trying\n> > to bend over backwards to avoid any reference to people's gender. It\n> > just makes for better documentation.\n> \n> I actually do not mind cast of characters with concrete names,\n> especially when there are more than three parties involved and\n> having names for them help clarify the description.  But I agree\n> with you that Alice and Bob should be reserved for situations where\n> appearance of Eve would reasonably be anticipated, or the use of\n> these two names become distracting to those who happen to be aware\n> how these characters are often used in CS literature.\n> \n> Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?\n\nI don't know anybody named Tabby or Fido (or at least any human).\n\nMaybe Mary and John, or Linda and James.\n\n-- \nFelipe Contreras"},{"id":"427636","messageId":"011201d762f2$f82522f0$e86f68d0$@nexbridge.com","threadId":"55934","inReplyTo":"60ca66304a0a0_6027208c8@natae.notmuch","subject":"RE: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2021-06-16T21:02:45Z","receivedAt":"2021-06-16T21:02:56Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":">From: Felipe Contreras <felipe.contreras@gmail.com>\n>Sent: June 16, 2021 4:59 PM\n>To: Junio C Hamano <gitster@pobox.com>; Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n>Cc: git@vger.kernel.org; Derrick Stolee <stolee@gmail.com>; Jeff King <peff@peff.net>; Felipe Contreras <felipe.contreras@gmail.com>;\n>Bagas Sanjaya <bagasdotme@gmail.com>; Robert Karszniewicz <avoidr@posteo.de>; Emily Shaffer <emilyshaffer@google.com>\n>Subject: Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples\n>\n>Junio C Hamano wrote:\n>> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>>\n>> > I suggested in [1] that the \"alice\" and \"bob\" examples in our\n>> > documentation would be better written without a reference to such\n>> > fictional characters, for reasons that have nothing to do with\n>> > trying to bend over backwards to avoid any reference to people's\n>> > gender. It just makes for better documentation.\n>>\n>> I actually do not mind cast of characters with concrete names,\n>> especially when there are more than three parties involved and having\n>> names for them help clarify the description.  But I agree with you\n>> that Alice and Bob should be reserved for situations where appearance\n>> of Eve would reasonably be anticipated, or the use of these two names\n>> become distracting to those who happen to be aware how these\n>> characters are often used in CS literature.\n>>\n>> Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?\n>\n>I don't know anybody named Tabby or Fido (or at least any human).\n>\n>Maybe Mary and John, or Linda and James.\n\nStevie, Jan, Pat, Chris, Randy, and Sue (if you're a Johnny Cash fan)\n\nI have used some of those in docs.\n\n"},{"id":"427637","messageId":"60ca674883abc_6027208d5@natae.notmuch","threadId":"55934","inReplyTo":"8250d8af-2d52-321c-36a7-d71c29fc1ef1@gmail.com","subject":"Re: [PATCH 1/6] gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-16T21:04:08Z","receivedAt":"2021-06-16T21:04:12Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 15/06/21 23.17, Ævar Arnfjörð Bjarmason wrote:\n> > -Suppose that Alice has started a new project with a Git repository in\n> > -/home/alice/project, and that Bob, who has a home directory on the\n> > -same machine, wants to contribute.\n> > +Suppose that you've started a new project with a Git repository in\n> > +/home/you/project, and you'd like another user on the same local\n> > +machine to be able to contribute to it. E.g. a www-data user to serve\n> > +the content up with a webserver.\n> >   \n> > -Bob begins with:\n> > +As the `www-data` user do:\n> >    >   ------------------------------------------------\n> > -bob$ git clone /home/alice/project myrepo\n> > +www-data$ git clone /home/you/project /var/www-data/deployment\n> >   ------------------------------------------------\n> > \n> \n> This assumes that we're on Debian or its derivatives,\n\nTrue, and not all derivatives. In Ubuntu it's /var/www/.\n\n-- \nFelipe Contreras"},{"id":"427763","messageId":"87pmwkh4he.fsf@vps.thesusis.net","threadId":"55934","inReplyTo":"60ca6586607f5_602720852@natae.notmuch","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Phillip Susi","fromEmail":"phill@thesusis.net","sentAt":"2021-06-17T15:48:00Z","receivedAt":"2021-06-17T15:54:24Z","isPatch":true,"sender":{"key":"phill@thesusis.net","avatar":null},"body":"\nFelipe Contreras <felipe.contreras@gmail.com> writes:\n\n> I have not read cryptography documentation, so for me Alice and Bob are\n> simply two illustrative colleagues.\n\nI have read cryptography documentation and seen Alice and Bob used\ncommonly.  Am I supposed to be confused if I see those names used in\ndocumentation for non cryptographic software?  If Alice and Bob work\nthere, why should they not be used here?  Am I missing something?\n\n>> And as argued in 1/6 for those users who /are/ aware of \"Alice and Bob\"\n>> it's needless distraction. Maybe it's just me, but whenever I read\n>> references to them I keep waiting for the cryptography angle to be\n>> introduced. None of the uses in our documentation reflect that canonical\n>> usage.\n>\n> It's probably not just you, but the vast majority of readers are\n> likely not aware of any cryptographic reference.\n\nI find it surprising that anyone would be upset that the names Alice and\nBob were being used in a non cryptographic context.\n\n>> There's also just weird things in our documentation fixed by this\n>> series, such as referring to a random file tracked by git as \"bob\"\n>> instead of the more obvious \"file.txt\".\n>\n> OK, _that_ I agree it's unequivocally an improvement.\n\nYea, a file probably shouldn't be called bob... I would probably have\ngone with \"foo.txt\" ( but file.txt is just fine too ).\n\n"},{"id":"427786","messageId":"875yyc5i6x.fsf@evledraar.gmail.com","threadId":"55934","inReplyTo":"8250d8af-2d52-321c-36a7-d71c29fc1ef1@gmail.com","subject":"Re: [PATCH 1/6] gittutorial doc: replace \"alice\" and \"bob\" with \"you\" and \"www-data\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-17T20:38:24Z","receivedAt":"2021-06-17T20:50:52Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Jun 16 2021, Bagas Sanjaya wrote:\n\n> On 15/06/21 23.17, Ævar Arnfjörð Bjarmason wrote:\n>> -Suppose that Alice has started a new project with a Git repository in\n>> -/home/alice/project, and that Bob, who has a home directory on the\n>> -same machine, wants to contribute.\n>> +Suppose that you've started a new project with a Git repository in\n>> +/home/you/project, and you'd like another user on the same local\n>> +machine to be able to contribute to it. E.g. a www-data user to serve\n>> +the content up with a webserver.\n>>   -Bob begins with:\n>> +As the `www-data` user do:\n>>    >   ------------------------------------------------\n>> -bob$ git clone /home/alice/project myrepo\n>> +www-data$ git clone /home/you/project /var/www-data/deployment\n>>   ------------------------------------------------\n>> \n>\n> This assumes that we're on Debian or its derivatives, however many\n> users run Git on other distributions (Fedora, Arch, Gentoo, openSUSE,\n> etc.), so `www-data` user may not be present there. Also, `www-data`\n> is system account, as opposed to normal user account, so you can't log\n> in to it; you need as root `chown -R www-data:www-data /somewhere/`.\n>\n> This also assumes that we use Apache HTTPD. The setup for other\n> webservers may be different. For example, if NGINX is used (installed \n> from upstream packages rather than from Debian package repository),\n> you need to make site root (the path specified in `root` directive)\n> readable by `nginx` user.\n\nI meant www-data merely as an example, the user is expected to fill in\nthe blanks as Junio noted downthread. Not all *nix systems even have\n$HOME in /home.\n\nBut clearly it's confusing to some, do you think calling it\ns/www-data/website/g and otherwise making it non-distro specific would\nbe better?\n\n>> -This creates a new directory \"myrepo\" containing a clone of Alice's\n>> +This creates a new directory \"deployment\" containing a clone of your\n>>   repository.  The clone is on an equal footing with the original\n>>   project, possessing its own copy of the original project's history.\n>>  \n>\n> But the scenario is we're cloning from local repo, so `git clone` here\n> implies --local (and bypasses normal Git transport mechanism), so to\n> get clone experience similar to when using remote repo, we can use \n> --no-local instead.\n\nWell spotted, I believe that was the behavior when this was writen at\n927a503cd0 (New tutorial, 2006-01-22), so this bug has probably always\nbeen there...\n\n>> -Bob then makes some changes and commits them:\n>> +As `www-data` you then makes some changes and commit them:\n>>     ------------------------------------------------\n>>   (edit files)\n>> -bob$ git commit -a\n>> +www-data$ git commit -a\n>>   (repeat as necessary)\n>>   ------------------------------------------------\n>>   -When he's ready, he tells Alice to pull changes from the\n>> repository\n>> -at /home/bob/myrepo.  She does this with:\n>> +You can then pull those changes to the checkout in your home directory\n>> +at /home/you/project:\n>>     ------------------------------------------------\n>> -alice$ cd /home/alice/project\n>> -alice$ git pull /home/bob/myrepo master\n>> +you$ cd /home/you/project\n>> +you$ git pull /var/www-data/deployment master\n>>   ------------------------------------------------\n>>   \n>\n> The resulting rewrite until this point makes no sense for\n> me. Previously we have Alice and Bob working the project, but now you\n> do the same, one as normal user account and one as system user\n> `www-data`. Honestly I would like keeping the status quo.\n\nCollectively we're a sample size of two, so it doesn't say much either\nway, but FWIW I've worked at two companies in the past that had some\nversion of the pattern discussed in this article. I.e. you'd login to\nsome machine, have a repo in $HOME, and used that as your staging area\nto another repo on the same machine also under your control (either\npermanently or exclusively, or you'd \"lock\" it for the duration).\n\nI don't think I've once in all my time using git been in the position to\nbe logged into a machine, and pulling/pushing to another repo in someone\nelse's $HOME or equivalent.\n\nIn any case, I do think for the purposes of the example in the guide\nreplacing Alice & Bob with You & another version of you removes a lot of\npotential confusion, we don't need to cover permissions, the other user\ndoing unexpected things like non-ff updates, pruning branches you may\nhave relied on through the --local clone etc.\n\nIt's implicit that both \"users\" are you, so we only have to discuss the\npoint of the actual example, how to pull and push between two different\nrepos, the \"different users\" in this case was always a distraction.\n"},{"id":"427788","messageId":"8735tg5hv7.fsf@evledraar.gmail.com","threadId":"55934","inReplyTo":"87pmwkh4he.fsf@vps.thesusis.net","subject":"Re: [PATCH 0/6] doc: replace \"alice\" and \"bob\" examples","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-17T20:51:19Z","receivedAt":"2021-06-17T20:57:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Jun 17 2021, Phillip Susi wrote:\n\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n>\n>> I have not read cryptography documentation, so for me Alice and Bob are\n>> simply two illustrative colleagues.\n>\n> I have read cryptography documentation and seen Alice and Bob used\n> commonly.  Am I supposed to be confused if I see those names used in\n> documentation for non cryptographic software?  If Alice and Bob work\n> there, why should they not be used here?  Am I missing something?\n>\n>>> And as argued in 1/6 for those users who /are/ aware of \"Alice and Bob\"\n>>> it's needless distraction. Maybe it's just me, but whenever I read\n>>> references to them I keep waiting for the cryptography angle to be\n>>> introduced. None of the uses in our documentation reflect that canonical\n>>> usage.\n>>\n>> It's probably not just you, but the vast majority of readers are\n>> likely not aware of any cryptographic reference.\n>\n> I find it surprising that anyone would be upset that the names Alice and\n> Bob were being used in a non cryptographic context.\n\nWho's upset? Not the author of this patch series, as noted in 1/6 I just\nthink it makes for less confusing reading, since Alice & Bob in\nparticular have implicit meanings you might guess at[1], and aside from\nthat I think it simplifies the example the guide is getting at [2].\n\n>>> There's also just weird things in our documentation fixed by this\n>>> series, such as referring to a random file tracked by git as \"bob\"\n>>> instead of the more obvious \"file.txt\".\n>>\n>> OK, _that_ I agree it's unequivocally an improvement.\n>\n> Yea, a file probably shouldn't be called bob... I would probably have\n> gone with \"foo.txt\" ( but file.txt is just fine too ).\n\nGit's documentation is read by all sorts of audiences, \"foo\" and \"bar\"\nare programmer jargon not obvious to everyone. I wouldn't say don't use\nit at all, but when a self-descriptive alternative such as file.txt or\nwhatever works perfectly fine as in the case changed in this series,\nit's better to go with that.\n\n1. http://lore.kernel.org/git/patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com\n2. https://lore.kernel.org/git/875yyc5i6x.fsf@evledraar.gmail.com/\n"}]}