git/Documentation
brian m. carlson dbbd2e7ee3 hex: allow only lowercase object IDs in breaking changes mode
Git has historically allowed either lowercase or uppercase hex for
object IDs, but it has always emitted only lowercase.  This has caused
people to expect only lowercase and not handle uppercase.

As an example, Git's own example hooks look for "[0-9a-f]" in several
places, but there are many other Git-adjacent pieces of software,
including Gitolite, which make the assumption that object IDs are always
lowercase.  This is not to criticize the authors of these projects, but
rather to point out how common this assumption is.  In fact, it's so
common that we had only one test in our codebase that failed when we
reject uppercase object IDs.

More critically, it leads people to make security-based assumptions that
an object ID either does not contain uppercase characters or that an
object ID can be expressed uniquely in hex form, neither of which are
currently true.  Git itself normally uses binary object IDs, which
avoids many of these problems, but most other projects deal primarily in
hex object IDs, so they are more affected.

In preparation for Git 3.0, only allow lowercase hex object IDs in
breaking changes mode and document this as well.  Add a new test to
verify we reject new uppercase object IDs.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2026-09-07 14:07:22 -07:00
..
RelNotes The 10th batch 2026-08-03 09:31:30 -07:00
config Merge branch 'hn/url-push-tracking' 2026-08-03 09:31:29 -07:00
howto meson: make GIT_HTML_PATH configurable 2025-11-06 09:58:56 -08:00
includes
mergetools
technical Merge branch 'ak/typofixes' 2026-06-15 07:42:00 -07:00
.gitignore
BreakingChanges.adoc hex: allow only lowercase object IDs in breaking changes mode 2026-09-07 14:07:22 -07:00
CodingGuidelines Merge branch 'jc/doc-timestamps-in-stat' 2026-05-11 10:05:54 +09:00
DecisionMaking.adoc
Makefile Merge branch 'en/xdiff-cleanup-2' 2025-12-05 14:49:56 +09:00
MyFirstContribution.adoc Merge branch 'wy/doc-myfirstcontribution-trim-quotes' 2026-07-19 10:42:18 -07:00
MyFirstObjectWalk.adoc
ReviewingGuidelines.adoc
SubmittingPatches Merge branch 'jc/submitting-patches-abandoning' 2026-07-19 10:42:16 -07:00
ToolsForGit.adoc
asciidoc.conf.in doc: convert git-bisect to synopsis style 2026-05-25 20:05:44 +09:00
asciidoctor-extensions.rb.in
blame-options.adoc doc: blame-options: convert to new doc format 2026-01-09 06:15:31 -08:00
build-docdep.perl
cat-texi.perl
cmd-list.sh
config.adoc config: add "worktree" and "worktree/i" includeIf conditions 2026-07-10 08:19:15 -07:00
date-formats.adoc doc: document and test `@` prefix for raw timestamps 2026-06-02 18:13:12 +09:00
diff-algorithm-option.adoc blame: make diff algorithm configurable 2025-11-17 09:31:59 -08:00
diff-context-options.adoc diff: document -U without <n> as using default context 2026-03-10 06:17:59 -07:00
diff-format.adoc diff-format.adoc: mode and hash are 0* for unmerged paths from index only 2026-05-16 22:21:37 +09:00
diff-generate-patch.adoc
diff-options.adoc Merge branch 'mm/doc-word-diff' 2026-06-11 04:31:19 -07:00
doc-diff
docbook-xsl.css
docbook.xsl
docinfo-html.in
everyday.adoco
fetch-options.adoc Merge branch 'wy/docs-typofixes' 2026-06-16 09:01:03 -07:00
fix-texi.sh
for-each-ref-options.adoc doc: fix some style issues in git-clone and for-each-ref-options 2026-02-05 21:14:05 -08:00
format-patch-caveats.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
format-patch-end-of-commit-message.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
fsck-msgids.adoc builtin/fsck: move generic HEAD check into `refs_fsck()` 2026-01-12 06:55:41 -08:00
generate-mergetool-list.sh
git-add.adoc Documentation: update add --force option + ignore=all config 2026-02-06 09:43:26 -08:00
git-am.adoc doc: convert git-am synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-annotate.adoc
git-apply.adoc doc: convert git-apply synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-archimport.adoc
git-archive.adoc archive: document --prefix handling of absolute and parent paths 2026-04-08 11:13:52 -07:00
git-backfill.adoc pack-objects: support sparse:oid filter with path-walk 2026-05-24 18:41:06 +09:00
git-bisect-lk2009.adoc
git-bisect.adoc doc: git bisect: clarify the usage of the synopsis vs actual command 2026-05-25 20:05:44 +09:00
git-blame.adoc blame: reserve mark column only if necessary 2026-07-06 07:34:48 -07:00
git-branch.adoc
git-bugreport.adoc
git-bundle.adoc
git-cat-file.adoc cat-file: add remote-object-info to batch-command 2026-07-24 08:49:09 -07:00
git-check-attr.adoc
git-check-ignore.adoc
git-check-mailmap.adoc
git-check-ref-format.adoc
git-checkout-index.adoc
git-checkout.adoc checkout -m: autostash when switching branches 2026-04-29 21:46:03 +09:00
git-cherry-pick.adoc
git-cherry.adoc
git-citool.adoc
git-clean.adoc
git-clone.adoc Merge branch 'cc/lop-filter-auto' 2026-02-25 11:54:17 -08:00
git-column.adoc
git-commit-graph.adoc doc: add caveat about turning off commit-graph 2026-05-08 10:22:33 +09:00
git-commit-tree.adoc
git-commit.adoc doc: commit: link to git-status(1) on all format options 2025-11-14 08:56:35 -08:00
git-config.adoc doc: git-config: escape erroneous highlight markup 2026-06-11 12:08:17 -07:00
git-count-objects.adoc Merge branch 'ds/doc-count-objects-fix' into maint-2.51 2025-10-14 13:40:54 -07:00
git-credential-cache--daemon.adoc
git-credential-cache.adoc
git-credential-store.adoc
git-credential.adoc
git-cvsexportcommit.adoc
git-cvsimport.adoc
git-cvsserver.adoc
git-daemon.adoc
git-describe.adoc doc: convert git-describe manual page to synopsis style 2026-04-06 09:38:19 -07:00
git-diagnose.adoc
git-diff-files.adoc
git-diff-index.adoc
git-diff-pairs.adoc
git-diff-tree.adoc
git-diff.adoc
git-difftool.adoc doc: convert git-difftool manual page to synopsis style 2026-04-06 09:38:18 -07:00
git-fast-export.adoc fast-export: standardize usage string and SYNOPSIS 2026-07-13 08:54:29 -07:00
git-fast-import.adoc fast-import: add 'strip-if-invalid' mode to '--signed-tags=<mode>' 2026-03-26 12:42:57 -07:00
git-fetch-pack.adoc
git-fetch.adoc doc: convert git fetch to synopsis style 2025-11-19 15:00:37 -08:00
git-filter-branch.adoc
git-fmt-merge-msg.adoc
git-for-each-ref.adoc
git-for-each-repo.adoc
git-format-patch.adoc Documentation: remove redundant 'instead' in --subject-prefix 2026-06-05 22:44:36 +09:00
git-format-rev.adoc docs: fix typos 2026-06-05 22:27:24 +09:00
git-fsck-objects.adoc
git-fsck.adoc
git-fsmonitor--daemon.adoc fsmonitor: implement filesystem change listener for Linux 2026-04-15 08:44:33 -07:00
git-gc.adoc
git-get-tar-commit-id.adoc
git-grep.adoc doc: convert git-grep synopsis and options to new style 2026-05-25 20:05:44 +09:00
git-gui.adoc
git-hash-object.adoc
git-help.adoc
git-history.adoc builtin/history: implement "drop" subcommand 2026-07-03 10:32:47 -07:00
git-hook.adoc doc: hook: don’t self-link via config include 2026-05-22 09:36:20 +09:00
git-http-backend.adoc
git-http-fetch.adoc
git-http-push.adoc
git-imap-send.adoc doc: convert git-imap-send synopsis and options to new style 2026-05-25 20:05:45 +09:00
git-index-pack.adoc
git-init-db.adoc
git-init.adoc
git-instaweb.adoc
git-interpret-trailers.adoc doc: interpret-trailers: normalize and fill out options 2026-03-16 15:04:37 -07:00
git-last-modified.adoc last-modified: change default max-depth to 0 2026-01-20 14:13:04 -08:00
git-log.adoc doc: log: use the same delimiter in description list 2026-04-28 09:46:26 +09:00
git-ls-files.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
git-ls-remote.adoc
git-ls-tree.adoc
git-mailinfo.adoc
git-mailsplit.adoc
git-maintenance.adoc maintenance: add 'is-needed' subcommand 2025-11-10 09:28:48 -08:00
git-merge-base.adoc
git-merge-file.adoc merge-file: honor merge.conflictStyle outside of a repository 2026-02-07 17:04:26 -08:00
git-merge-index.adoc
git-merge-one-file.adoc
git-merge-tree.adoc
git-merge.adoc
git-mergetool--lib.adoc
git-mergetool.adoc
git-mktag.adoc
git-mktree.adoc
git-multi-pack-index.adoc midx: support custom `--base` for incremental MIDX writes 2026-05-20 11:31:13 +09:00
git-mv.adoc
git-name-rev.adoc
git-notes.adoc
git-p4.adoc
git-pack-objects.adoc pack-objects: support `--delta-islands` with `--path-walk` 2026-06-21 16:26:14 -07:00
git-pack-redundant.adoc
git-pack-refs.adoc
git-patch-id.adoc doc: patch-id: see also git-cherry(1) 2026-02-17 10:49:51 -08:00
git-prune-packed.adoc
git-prune.adoc
git-pull.adoc Merge branch 'je/doc-pull' 2025-12-14 17:04:37 +09:00
git-push.adoc push: support pushing to a remote group 2026-05-04 10:11:17 +09:00
git-quiltimport.adoc
git-range-diff.adoc Merge branch 'sp/doc-range-diff-takes-notes' 2026-05-31 10:00:39 +09:00
git-read-tree.adoc
git-rebase.adoc rebase: support --trailer 2026-03-06 13:02:20 -08:00
git-receive-pack.adoc
git-reflog.adoc
git-refs.adoc builtin/refs: add "rename" subcommand 2026-07-06 07:45:57 -07:00
git-remote-ext.adoc
git-remote-fd.adoc
git-remote-helpers.adoco
git-remote.adoc doc: convert git-remote to synopsis style 2025-12-21 11:33:10 +09:00
git-repack.adoc repack: allow `--write-midx=incremental` without `--geometric` 2026-05-20 11:31:14 +09:00
git-replace.adoc doc: add caveat about turning off commit-graph 2026-05-08 10:22:33 +09:00
git-replay.adoc replay: allow to specify a ref with option --ref 2026-04-01 21:34:25 -07:00
git-repo.adoc repo: add path.gitdir with absolute and relative suffix formatting 2026-06-23 21:15:52 -07:00
git-request-pull.adoc
git-rerere.adoc doc: fix singular/plural mismatch in git-rerere 2026-04-16 21:22:01 -07:00
git-reset.adoc doc: git-reset: clarify `git reset <pathspec>` 2026-01-06 08:10:14 +09:00
git-restore.adoc Merge branch 'kh/doc-restore-double-underscores-fix' 2026-05-19 09:57:45 +09:00
git-rev-list.adoc
git-rev-parse.adoc Merge branch 'bc/sha1-256-interop-01' 2025-10-22 11:38:58 -07:00
git-revert.adoc
git-rm.adoc
git-send-email.adoc Merge branch 'dt/send-email-client-cert' 2026-03-12 10:56:05 -07:00
git-send-pack.adoc
git-sh-i18n--envsubst.adoc
git-sh-i18n.adoc
git-sh-setup.adoc
git-shell.adoc
git-shortlog.adoc doc: convert git-shortlog manual page to synopsis style 2026-04-06 09:38:19 -07:00
git-show-branch.adoc
git-show-index.adoc
git-show-ref.adoc
git-show.adoc doc: convert git-show to synopsis style 2026-02-05 21:14:05 -08:00
git-sparse-checkout.adoc doc: fix typos via codespell 2026-06-08 00:21:35 +09:00
git-stage.adoc doc: convert git stage to use synopsis block 2025-12-21 11:33:10 +09:00
git-stash.adoc stash: add --label-ours, --label-theirs, --label-base for apply 2026-04-29 21:46:02 +09:00
git-status.adoc doc: convert git-status tables to AsciiDoc format 2025-12-21 11:33:10 +09:00
git-stripspace.adoc
git-submodule.adoc doc: convert git-submodule to synopsis style 2026-02-05 21:14:05 -08:00
git-svn.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
git-switch.adoc checkout -m: autostash when switching branches 2026-04-29 21:46:03 +09:00
git-symbolic-ref.adoc
git-tag.adoc Merge branch 'cc/fast-import-strip-signed-tags' 2025-10-28 10:29:09 -07:00
git-tools.adoc
git-unpack-file.adoc
git-unpack-objects.adoc
git-update-index.adoc
git-update-ref.adoc Merge branch 'sb/doc-update-ref-markup-fix' 2026-01-23 13:34:35 -08:00
git-update-server-info.adoc
git-upload-archive.adoc
git-upload-pack.adoc
git-url-parse.adoc doc: describe the url-parse builtin 2026-05-06 09:48:29 +09:00
git-var.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00
git-verify-commit.adoc
git-verify-pack.adoc
git-verify-tag.adoc
git-version.adoc
git-web--browse.adoc
git-whatchanged.adoc
git-worktree.adoc Merge branch 'sb/doc-worktree-prune-expire-improvement' 2026-02-09 12:09:10 -08:00
git-write-tree.adoc
git.adoc Merge branch 'os/doc-git-custom-commands' 2026-03-16 10:48:14 -07:00
gitattributes.adoc userdiff: add support for Swift 2026-07-23 07:14:34 -07:00
gitcli.adoc doc: clarify command equivalence comment 2025-11-04 09:25:51 -08:00
gitcore-tutorial.adoc
gitcredentials.adoc Merge branch 'mh/doc-credential-url-prefix' into maint-2.51 2025-10-15 10:29:35 -07:00
gitcvs-migration.adoc doc: gitcvs-migration: rephrase “man page” 2026-04-06 09:57:07 -07:00
gitdatamodel.adoc doc: remove stray text in Git data model 2025-12-03 00:17:07 -08:00
gitdiffcore.adoc
giteveryday.adoc
gitfaq.adoc Merge branch 'bc/doc-stash-import-export' 2026-01-16 12:40:27 -08:00
gitformat-bundle.adoc
gitformat-chunk.adoc
gitformat-commit-graph.adoc
gitformat-index.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
gitformat-loose.adoc rust: add a new binary object map format 2026-02-07 17:41:03 -08:00
gitformat-pack.adoc midx: do not require packs to be sorted in lexicographic order 2026-02-24 11:16:33 -08:00
gitformat-signature.adoc
gitglossary.adoc
githooks.adoc refs: add 'preparing' phase to the reference-transaction hook 2026-03-16 21:00:44 -07:00
gitignore.adoc ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR 2026-05-13 10:25:52 +09:00
gitk.adoc Merge branch 'js/doc-gitk-history' into maint-2.51 2025-10-14 13:40:53 -07:00
gitmailmap.adoc
gitmodules.adoc doc: fix grammar errors in submodule description 2026-04-16 21:22:01 -07:00
gitnamespaces.adoc
gitpacking.adoc Documentation: fix broken `sampleRate` in gitpacking(7) 2026-05-12 10:36:18 +09:00
gitprotocol-capabilities.adoc
gitprotocol-common.adoc
gitprotocol-http.adoc doc: clarify server behavior for invalid 'want' lines in HTTP protocol 2025-11-06 09:45:38 -08:00
gitprotocol-pack.adoc doc: gitprotocol-pack: normalize italic formatting 2026-03-02 21:35:05 -08:00
gitprotocol-v2.adoc protocol-caps: check object existence regardless of the attributes requested 2026-07-24 08:46:59 -07:00
gitremote-helpers.adoc
gitrepository-layout.adoc
gitrevisions.adoc
gitsubmodules.adoc
gittutorial-2.adoc
gittutorial.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00
gitweb.adoc
gitweb.conf.adoc
gitworkflows.adoc
glossary-content.adoc gitglossary: fix indentation of sub-lists 2026-04-13 11:50:06 -07:00
i18n.adoc
install-doc-quick.sh
install-webdoc.sh
line-range-format.adoc
line-range-options.adoc line-log: allow non-patch diff formats with -L 2026-05-29 14:06:21 +09:00
lint-delimited-sections.perl
lint-documentation-style.perl
lint-fsck-msgids.perl
lint-gitlink.perl lint-gitlink: preemptively ignore all /ifn?def|endif/ macros 2026-01-21 08:26:00 -08:00
lint-man-end-blurb.perl
lint-man-section-order.perl
lint-manpages.sh
manpage-bold-literal.xsl
manpage-normal.xsl
manpage.xsl
merge-options.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
merge-strategies.adoc
meson.build Merge branch 'mm/git-url-parse' 2026-05-21 12:06:48 +09:00
object-format-disclaimer.adoc
pack-refs-options.adoc
pretty-formats.adoc docs/pretty-formats: add %(count) and %(total) 2026-03-23 13:06:58 -07:00
pretty-options.adoc
pull-fetch-param.adoc doc: pull-fetch-param typofix 2025-11-24 10:55:48 -08:00
ref-reachability-filters.adoc
ref-storage-format.adoc docs: correct information about reftable 2026-04-08 07:18:56 -07:00
rerere-options.adoc doc: rerere-options.adoc: link to git-rerere(1) 2026-02-10 12:27:07 -08:00
rev-list-description.adoc
rev-list-options.adoc graph: add --[no-]graph-indent and log.graphIndent 2026-07-14 07:32:51 -07:00
revisions.adoc remote: find tracking branches for URL push destinations 2026-07-22 11:29:49 -07:00
scalar.adoc scalar: document config settings 2025-12-16 09:42:44 +09:00
sequencer.adoc
signoff-option.adoc signoff-option: linkify the reference to gitfaq 2025-12-19 21:51:01 +09:00
texi.xsl
trace2-target-values.adoc
transfer-data-leaks.adoc
urls-remotes.adoc doc: convert git pull to synopsis style 2025-11-19 15:00:42 -08:00
urls.adoc
user-manual.adoc doc: replace git config --list/-l with `list` 2026-04-06 09:57:07 -07:00