git-commit-vandalism/Documentation
Junio C Hamano 5b1cd37e44 CodingGuidelines: recommend gender-neutral description
Technical writing seeks to convey information with minimal
friction. One way that a reader can experience friction is if they
encounter a description of "a user" that is later simplified using a
gendered pronoun. If the reader does not consider that pronoun to
apply to them, then they can experience cognitive dissonance that
removes focus from the information.

Give some basic tips to guide us avoid unnecessary uses of gendered
description.

Using a gendered pronoun is appropriate when referring to a specific
person.

There are acceptable existing uses of gendered pronouns within the
Git codebase, such as:

* References to real people (e.g. Linus Torvalds, "the Git maintainer").
  Do not misgender real people. If there is any doubt to the gender of a
  person, then avoid using pronouns.

* References to fictional people with clear genders (e.g. Alice and
  Bob).

* Sample text used in test cases (e.g t3702, t6432).

* The official text of the GPL license contains uses of "he or she",
  but using singular "they" (or modifying the text in some other
  way) is not within the scope of the Git project.

* Literal email messages in Documentation/howto/ should not be edited
  for grammatical concerns such as this, unless we update the entire
  document to fit the standard documentation format. If such an effort is
  taken on, then the authorship would change and no longer refer to the
  exact mail message.

* External projects consumed in contrib/ should not deviate solely for
  style reasons. Recommended edits should be contributed to those
  projects directly.

Other cases within the Git project were cleaned up by the previous
changes.

Co-authored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-07-16 11:35:46 -07:00
..
config Merge branch 'jn/mergetool-hideresolved-is-optional' 2021-03-14 16:01:41 -07:00
howto Merge branch 'js/pu-to-seen' 2020-07-06 22:09:16 -07:00
RelNotes Git 2.31.1 2021-03-26 14:49:41 -07:00
technical Merge branch 'hn/reftable-tables-doc-update' 2021-03-01 14:02:57 -08:00
.gitattributes
.gitignore Merge branch 'js/misc-doc-fixes' 2019-05-09 00:37:27 +09:00
asciidoc.conf Doc: drop support for docbook-xsl before 1.72.0 2020-03-29 09:25:38 -07:00
asciidoctor-extensions.rb Merge branch 'ma/user-manual-markup-update' 2019-10-06 12:25:16 +09:00
blame-options.txt blame-options.txt: camelcase blame.blankBoundary 2021-02-24 15:21:25 -08:00
build-docdep.perl
cat-texi.perl
cmd-list.perl git.txt: add list of guides 2020-08-04 18:34:02 -07:00
CodingGuidelines CodingGuidelines: recommend gender-neutral description 2021-07-16 11:35:46 -07:00
config.txt Merge branch 'km/config-doc-typofix' 2021-03-19 15:25:38 -07:00
date-formats.txt doc: mention approxidates for git-commit --date 2021-02-23 13:33:02 -08:00
diff-format.txt doc: indent multi-line items in list 2019-12-13 12:18:07 -08:00
diff-generate-patch.txt doc/diff-generate-patch: mention new --diff-merges option 2020-12-21 13:47:32 -08:00
diff-options.txt diff: --{rotate,skip}-to=<path> 2021-02-16 09:30:42 -08:00
doc-diff doc-diff: use single-colon rule in rendering Makefile 2020-02-18 13:53:30 -08:00
docbook-xsl.css
docbook.xsl
everyday.txto
fetch-options.txt fetch: implement support for atomic reference updates 2021-01-12 12:06:15 -08:00
fix-texi.perl
git-add.txt add: support the --pathspec-from-file option 2019-12-04 10:10:37 -08:00
git-am.txt i18n.txt: camel case and monospace "i18n.commitEncoding" 2021-02-24 15:21:25 -08:00
git-annotate.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-apply.txt git-apply.txt: update descriptions of --cached, --index 2020-08-20 16:34:37 -07:00
git-archimport.txt git-archimport.1: specify what kind of Arch we're talking about 2018-09-21 09:28:58 -07:00
git-archive.txt archive: add --add-file 2020-09-19 15:56:06 -07:00
git-bisect-lk2009.txt git-bisect-lk2009: make continuation of list indented 2020-10-08 14:01:15 -07:00
git-bisect.txt bisect: swap command-line options in documentation 2020-08-28 14:06:06 -07:00
git-blame.txt mailmap doc: create a new "gitmailmap(5)" man page 2021-01-12 14:04:39 -08:00
git-branch.txt Merge branch 'jc/maint-column-doc-typofix' 2021-02-25 16:43:30 -08:00
git-bugreport.txt Merge branch 'es/bugreport-shell' 2020-06-08 18:06:28 -07:00
git-bundle.txt bundle: add new version for use with SHA-256 2020-07-30 09:16:48 -07:00
git-cat-file.txt cat-file: add missing [=<format>] to usage/synopsis 2020-07-01 15:54:05 -07:00
git-check-attr.txt Documentation: fix a bunch of typos, both old and new 2019-11-07 13:42:00 +09:00
git-check-ignore.txt Merge branch 'en/check-ignore' into maint 2020-03-17 15:02:23 -07:00
git-check-mailmap.txt check-mailmap doc: note config options 2021-01-12 14:04:40 -08:00
git-check-ref-format.txt doc: promote "git switch" 2019-04-02 13:57:00 +09:00
git-checkout-index.txt
git-checkout.txt Merge branch 'dl/checkout-guess' 2020-10-27 15:09:51 -07:00
git-cherry-pick.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
git-cherry.txt
git-citool.txt
git-clean.txt Merge branch 'en/clean-nested-with-ignored' 2019-10-11 14:24:46 +09:00
git-clone.txt Documentation/git-clone.txt: document race with --local 2021-01-11 22:03:08 -08:00
git-column.txt git-column.txt: fix section header 2018-12-26 15:29:30 -08:00
git-commit-graph.txt Merge branch 'ds/commit-graph-merging-fix' 2020-11-02 13:17:39 -08:00
git-commit-tree.txt Documentation: merge commit-tree --[no-]gpg-sign 2020-04-03 11:37:22 -07:00
git-commit.txt doc: preparatory clean-up of description on the sign-off option 2020-10-20 11:57:35 -07:00
git-config.txt Merge branch 'ps/config-env-pairs' 2021-01-25 14:19:19 -08:00
git-count-objects.txt
git-credential-cache--daemon.txt
git-credential-cache.txt Use proper syntax for replaceables in command docs 2018-05-25 17:16:47 +09:00
git-credential-store.txt Merge branch 'cb/credential-store-ignore-bogus-lines' 2020-05-08 14:25:01 -07:00
git-credential.txt git-credential.txt: use list continuation 2020-05-18 13:19:33 -07:00
git-cvsexportcommit.txt
git-cvsimport.txt
git-cvsserver.txt Documentation: fix a bunch of typos, both old and new 2019-11-07 13:42:00 +09:00
git-daemon.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-describe.txt describe doc: remove '7-char' abbreviation reference 2019-04-08 17:24:51 +09:00
git-diff-files.txt
git-diff-index.txt builtin/diff-index: learn --merge-base 2020-09-20 21:30:26 -07:00
git-diff-tree.txt builtin/diff-tree: learn --merge-base 2020-09-21 13:37:03 -07:00
git-diff.txt builtin/diff-tree: learn --merge-base 2020-09-21 13:37:03 -07:00
git-difftool.txt difftool.c: learn a new way start at specified file 2021-02-22 13:35:49 -08:00
git-fast-export.txt fast-export: allow seeding the anonymized mapping 2020-06-25 14:19:23 -07:00
git-fast-import.txt fast-import: fix typo in documentation 2020-10-04 12:56:29 -07:00
git-fetch-pack.txt Documentation: fix several one-character-off spelling errors 2018-04-09 14:15:02 +09:00
git-fetch.txt fetch: allow refspecs specified through stdin 2020-08-18 13:25:05 -07:00
git-filter-branch.txt filter-branch doc: fix filter-repo typo 2020-10-20 12:22:25 -07:00
git-fmt-merge-msg.txt config.txt: move fmt-merge-msg-config.txt to config/ 2018-10-29 10:17:01 +09:00
git-for-each-ref.txt ref-filter: use pretty.c logic for trailers 2021-02-15 16:48:38 -08:00
git-for-each-repo.txt for-each-repo: run subcommands on configured repos 2020-09-25 10:59:44 -07:00
git-format-patch.txt Merge branch 'jc/format-patch-name-max' 2020-11-21 15:14:38 -08:00
git-fsck-objects.txt
git-fsck.txt fsck doc: remove ancient out-of-date diagnostics 2021-01-20 19:10:42 -08:00
git-gc.txt docs: clarify that refs/notes/ do not keep the attached objects alive 2021-02-10 23:43:55 -08:00
git-get-tar-commit-id.txt
git-grep.txt doc: add more pointers to gitattributes(5) for userdiff 2020-11-01 15:54:14 -08:00
git-gui.txt Documentation: update the location of the git-gui repo 2019-10-06 09:45:02 +09:00
git-hash-object.txt hash-object doc: stop mentioning git-cvsimport 2019-05-28 10:47:42 -07:00
git-help.txt help: drop usage of 'common' and 'useful' for guides 2020-08-04 18:34:01 -07:00
git-http-backend.txt Documentation: turn middle-of-line tabs into spaces 2019-03-07 09:25:32 +09:00
git-http-fetch.txt http-fetch: allow custom index-pack args 2021-02-22 12:07:40 -08:00
git-http-push.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-imap-send.txt git-imap-send.txt: add note about localized Gmail folders 2020-08-31 11:44:33 -07:00
git-index-pack.txt Merge branch 'jt/transfer-fsck-across-packs' 2021-03-01 14:02:57 -08:00
git-init-db.txt
git-init.txt init: document init.defaultBranch better 2020-12-13 15:53:50 -08:00
git-instaweb.txt git-instaweb: add Python builtin http.server support 2019-01-28 10:57:44 -08:00
git-interpret-trailers.txt interpret-trailers.txt: start the desc line with a capital letter 2019-04-01 15:49:47 +09:00
git-log.txt Merge branch 'so/log-diff-merge' 2021-02-05 16:40:44 -08:00
git-ls-files.txt ls-files.c: add --deduplicate option 2021-01-23 11:48:20 -08:00
git-ls-remote.txt docs: adjust for the recent rename of pu to seen 2020-06-25 09:18:53 -07:00
git-ls-tree.txt doc: clarify that --abbrev=<n> is about the minimum length 2020-11-04 14:04:44 -08:00
git-mailinfo.txt i18n.txt: camel case and monospace "i18n.commitEncoding" 2021-02-24 15:21:25 -08:00
git-mailsplit.txt
git-maintenance.txt maintenance: add pack-refs task 2021-02-09 23:09:24 -08:00
git-merge-base.txt git-merge-base.txt: render indentations correctly under Asciidoctor 2019-09-09 11:05:51 -07:00
git-merge-file.txt
git-merge-index.txt git-merge-index.txt: wrap shell listing in "----" 2019-09-09 11:05:52 -07:00
git-merge-one-file.txt
git-merge-tree.txt
git-merge.txt Doc: reference the "stash list" in autostash docs 2020-05-05 16:07:30 -07:00
git-mergetool--lib.txt mergetool: break setup_tool out into separate initialization function 2021-02-09 14:09:16 -08:00
git-mergetool.txt doc: describe mergetool configuration in git-mergetool(1) 2021-03-13 15:34:32 -08:00
git-mktag.txt mktag: add a --[no-]strict option 2021-01-06 14:22:24 -08:00
git-mktree.txt Documentation: normalize spelling of 'normalised' 2018-04-09 14:15:07 +09:00
git-multi-pack-index.txt multi-pack-index: repack batches below --batch-size 2020-08-11 14:05:26 -07:00
git-mv.txt
git-name-rev.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-notes.txt docs: improve the example that illustrates git-notes path names 2020-08-03 12:40:09 -07:00
git-p4.txt doc: fix some typos 2021-01-04 11:27:48 -08:00
git-pack-objects.txt doc: mention bigFileThreshold for packing 2021-02-22 13:18:30 -08:00
git-pack-redundant.txt
git-pack-refs.txt
git-patch-id.txt doc: remove unsupported parameter from patch-id 2017-07-28 14:41:32 -07:00
git-prune-packed.txt
git-prune.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-pull.txt Merge branch 'dl/merge-autostash' 2020-04-29 16:15:27 -07:00
git-push.txt doc: avoid using the gender of other people 2021-06-16 11:25:09 +09:00
git-quiltimport.txt git-quiltimport: add --keep-non-patch option 2019-01-07 15:29:34 -08:00
git-range-diff.txt Merge branch 'js/range-diff-one-side-only' 2021-02-17 17:21:41 -08:00
git-read-tree.txt doc: --recurse-submodules mostly applies to active submodules 2020-04-06 13:42:43 -07:00
git-rebase.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
git-receive-pack.txt git-receive-pack.txt: wrap shell [script] listing in "----" 2019-09-09 11:05:52 -07:00
git-reflog.txt reflog expire: cover reflog from all worktrees 2018-10-22 13:32:54 +09:00
git-remote-ext.txt Merge branch 'js/check-docs-exe' 2019-04-22 11:14:46 +09:00
git-remote-fd.txt docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote-helpers.txto docs: move gitremote-helpers into section 7 2019-04-01 14:00:53 +09:00
git-remote.txt remote: add meaningful exit code on missing/existing 2020-10-27 11:40:33 -07:00
git-repack.txt doc: mention bigFileThreshold for packing 2021-02-22 13:18:30 -08:00
git-replace.txt Recommend git-filter-repo instead of git-filter-branch 2019-09-05 13:01:48 -07:00
git-request-pull.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-rerere.txt Merge branch 'nd/switch-and-restore' 2019-07-09 15:25:44 -07:00
git-reset.txt doc: document --recurse-submodules for reset and restore 2020-04-06 13:42:43 -07:00
git-restore.txt Doc: document "A...B" form for <tree-ish> in checkout and switch 2020-10-07 09:49:05 -07:00
git-rev-list.txt docs/rev-list: add some examples of --disk-usage 2021-02-17 16:25:29 -08:00
git-rev-parse.txt rev-parse: add option for absolute or relative path formatting 2020-12-12 23:35:51 -08:00
git-revert.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
git-rm.txt rm: support the --pathspec-from-file option 2020-02-19 10:56:49 -08:00
git-send-email.txt Merge branch 'vv/send-email-with-less-secure-apps-access' into maint 2021-02-05 16:31:25 -08:00
git-send-pack.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-sh-i18n--envsubst.txt
git-sh-i18n.txt
git-sh-setup.txt
git-shell.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-shortlog.txt mailmap: only look for .mailmap in work tree 2021-02-10 13:34:51 -08:00
git-show-branch.txt Documentation/git-show-branch: avoid literal {apostrophe} 2019-04-10 12:05:03 +09:00
git-show-index.txt Documentation: mark --object-format=sha256 as experimental 2020-08-17 10:50:14 -07:00
git-show-ref.txt git-show-ref.txt: fix order of flags 2019-01-10 10:29:05 -08:00
git-show.txt doc/git-show: include --diff-merges description 2020-12-21 13:47:32 -08:00
git-sparse-checkout.txt Merge branch 'en/sparse-with-submodule-doc' 2020-06-22 15:55:03 -07:00
git-stage.txt
git-stash.txt git-stash.txt: be explicit about subcommand options 2021-02-11 13:34:58 -08:00
git-status.txt Documentation: typofix --column description 2021-02-19 19:36:47 -08:00
git-stripspace.txt
git-submodule.txt submodule: fall back to remote's HEAD for missing remote.<name>.branch 2020-06-24 09:14:21 -07:00
git-svn.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
git-switch.txt checkout: learn to respect checkout.guess 2020-10-08 09:25:29 -07:00
git-symbolic-ref.txt
git-tag.txt Documentation: typofix --column description 2021-02-19 19:36:47 -08:00
git-tools.txt doc: replace or.cz gitwiki link with git.wiki.kernel.org 2017-04-20 22:05:37 -07:00
git-unpack-file.txt
git-unpack-objects.txt
git-update-index.txt doc: remove "directory cache" from man pages 2021-01-09 22:57:24 -08:00
git-update-ref.txt update-ref: allow creation of multiple transactions 2020-11-16 13:44:01 -08:00
git-update-server-info.txt update-server-info: avoid needless overwrites 2019-05-15 14:07:37 +09:00
git-upload-archive.txt
git-upload-pack.txt doc: tidy asciidoc style 2019-01-23 11:37:29 -08:00
git-var.txt doc: keep first level section header in upper case 2018-05-02 17:03:33 +09:00
git-verify-commit.txt
git-verify-pack.txt
git-verify-tag.txt
git-web--browse.txt doc: format pathnames and URLs as monospace. 2019-03-13 11:14:22 +09:00
git-whatchanged.txt
git-worktree.txt worktree: teach list verbose mode 2021-01-30 09:57:40 -08:00
git-write-tree.txt
git.txt git.txt: fix monospace rendering 2021-02-18 10:53:33 -08:00
gitattributes.txt userdiff: support Bash 2020-10-22 10:29:30 -07:00
gitcli.txt Merge branch 'jc/doc-single-h-is-for-help' into maint 2020-03-17 15:02:24 -07:00
gitcore-tutorial.txt doc/gitcore-tutorial: fix prose to match example command 2020-01-08 08:56:40 -08:00
gitcredentials.txt command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers' 2020-08-04 18:34:01 -07:00
gitcvs-migration.txt Merge branch 'sb/doc-unify-bottom' 2017-02-15 12:54:20 -08:00
gitdiffcore.txt Merge branch 'en/diffcore-rename' 2021-03-01 14:02:56 -08:00
giteveryday.txt docs: adjust for the recent rename of pu to seen 2020-06-25 09:18:53 -07:00
gitfaq.txt docs: explain how to deal with files that are always modified 2020-09-20 21:29:02 -07:00
gitglossary.txt Documentation: unify bottom "part of git suite" lines 2017-02-09 15:14:01 -08:00
githooks.txt doc: fix some typos 2021-01-04 11:27:48 -08:00
gitignore.txt Merge branch 'an/ignore-doc-update' into maint 2019-07-25 14:27:13 -07:00
gitk.txt doc: log, gitk: move '-L' description to 'line-range-options.txt' 2020-11-01 15:54:14 -08:00
gitmailmap.txt gitmailmap.txt: fix rendering of e-mail addresses 2021-02-18 10:53:33 -08:00
gitmodules.txt gitmodules.txt: fix 'GIT_WORK_TREE' variable name 2021-01-04 11:29:36 -08:00
gitnamespaces.txt
gitremote-helpers.txt Merge branch 'bc/sha-256-part-2' 2020-07-06 22:09:13 -07:00
gitrepository-layout.txt Merge branch 'sg/dir-trie-fixes' 2019-11-10 18:02:14 +09:00
gitrevisions.txt push doc: correct lies about how push refspecs work 2018-08-31 14:04:06 -07:00
gitsubmodules.txt gitsubmodules doc: invoke 'ls-files' with '--recurse-submodules' 2020-10-04 12:54:07 -07:00
gittutorial-2.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gittutorial.txt doc: promote "git restore" 2019-05-07 13:04:48 +09:00
gitweb.conf.txt gitweb.conf.txt: switch pluses to backticks to help Asciidoctor 2019-09-09 11:05:52 -07:00
gitweb.txt doc: don't use git.kernel.org as example gitweb URL 2019-06-24 12:37:21 -07:00
gitworkflows.txt gitworkflows.txt: fix broken subsection underline 2020-07-18 13:43:34 -07:00
glossary-content.txt glossary: improve "branch" definition 2020-12-02 14:53:42 -08:00
howto-index.sh
i18n.txt i18n.txt: camel case and monospace "i18n.commitEncoding" 2021-02-24 15:21:25 -08:00
install-doc-quick.sh install-doc-quick: allow specifying what ref to install 2017-12-12 16:49:40 -08:00
install-webdoc.sh
line-range-format.txt doc: add more pointers to gitattributes(5) for userdiff 2020-11-01 15:54:14 -08:00
line-range-options.txt blame-options.txt: also mention 'funcname' in '-L' description 2020-11-01 15:54:14 -08:00
lint-gitlink.perl
Makefile mailmap doc: create a new "gitmailmap(5)" man page 2021-01-12 14:04:39 -08:00
manpage-base-url.xsl.in
manpage-bold-literal.xsl manpage-bold-literal.xsl: stop using git.docbook.backslash 2020-03-29 09:25:38 -07:00
manpage-normal.xsl manpage-normal.xsl: fold in manpage-base.xsl 2020-03-29 09:25:38 -07:00
manpage-quote-apos.xsl
manpage.xsl Documentation: fix build with Asciidoctor 2 2019-09-16 12:20:39 -07:00
merge-options.txt doc: preparatory clean-up of description on the sign-off option 2020-10-20 11:57:35 -07:00
merge-strategies.txt merge-strategies: fix typo "reflected to" to "reflected in" 2019-11-11 11:04:46 +09:00
MyFirstContribution.txt tests: remove support for GIT_TEST_GETTEXT_POISON 2021-01-21 15:50:01 -08:00
MyFirstObjectWalk.txt MyFirstObjectWalk: drop init_walken_defaults() 2020-11-30 13:55:54 -08:00
object-format-disclaimer.txt Documentation: mark --object-format=sha256 as experimental 2020-08-17 10:50:14 -07:00
pretty-formats.txt pretty format %(trailers): add a "key_value_separator" 2020-12-09 14:16:42 -08:00
pretty-options.txt doc: clarify that --abbrev=<n> is about the minimum length 2020-11-04 14:04:44 -08:00
pull-fetch-param.txt refspec: add support for negative refspecs 2020-09-30 14:52:00 -07:00
ref-reachability-filters.txt Doc: prefer more specific file name 2020-09-18 15:41:56 -07:00
rev-list-description.txt git-log.txt: include rev-list-description.txt 2020-07-08 22:08:54 -07:00
rev-list-options.txt Merge branch 'ma/doc-markup-fix' 2021-02-25 16:43:30 -08:00
revisions.txt revisions.txt: describe 'rev1 rev2 ...' meaning for ranges 2020-07-08 22:08:53 -07:00
sequencer.txt cherry-pick/revert: add --skip option 2019-07-02 12:08:08 -07:00
signoff-option.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
SubmittingPatches doc: avoid using the gender of other people 2021-06-16 11:25:09 +09:00
texi.xsl
trace2-target-values.txt docs: mention trace2 target-dir mode in git-config 2019-10-04 09:26:42 +09:00
transfer-data-leaks.txt
urls-remotes.txt
urls.txt Doc: Bundle file usage 2019-10-21 12:02:39 +09:00
user-manual.conf user-manual.conf: don't specify [listingblock] 2020-03-31 16:08:02 -07:00
user-manual.txt doc: avoid using the gender of other people 2021-06-16 11:25:09 +09:00