kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity
git/Documentation
History
Junio C Hamano 1bc1e94091 doc: option value may be separate for valid reasons 
Even though `git help cli` recommends users to prefer using
"--option=value" over "--option value", there can be reasons why
giving them separately is a good idea.  One reason is that shells do
not perform tilde expansion for `--option=~/path/name` but they
expand `--options ~/path/name` just fine.

This is not a problem for many options whose option parsing is
properly written using OPT_FILENAME(), because the value given to
OPT_FILENAME() is tilde-expanded internally by us, but some commands
take a pathname as a mere string, which needs this trick to have the
shell help us.

I think the reason we originally decided to recommend the stuck form
was because an option that takes an optional value requires you to
use it in the stuck form, and it is one less thing for users to
worry about if they get into the habit to always use the stuck form.
But we should be discouraging ourselves from adding an option with
an optional value in the first place, and we might want to weaken
the current recommendation.

In any case, let's describe this one case where it is necessary to
use the separate form, with an example.

Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
 		2024-11-25 14:20:15 +09:00
..
RelNotes Prepare for 2.47.1 2024-11-20 14:43:30 +09:00
config Merge branch 'ak/doc-typofix' 2024-10-04 14:21:43 -07:00
howto howto-maintain-git: discarding inactive topics 2024-09-26 12:13:34 -07:00
includes
…
mergetools mergetools: vimdiff: use correct tool's name when reading mergetool config 2024-02-19 08:45:14 -08:00
technical Documentation/technical: fix a typo 2024-09-23 12:40:52 -07:00
.gitattributes
…
.gitignore Doc: fix Asciidoctor css workaround 2024-07-23 11:02:52 -07:00
BreakingChanges.txt Documentation: fix typos 2024-09-23 12:47:36 -07:00
CodingGuidelines Merge branch 'jc/coding-style-c-operator-with-spaces' into maint-2.46 2024-09-13 15:26:51 -07:00
DecisionMaking.txt Documentation: fix typos 2024-09-23 12:47:36 -07:00
Makefile Merge branch 'es/doc-platform-support-policy' 2024-08-15 13:22:13 -07:00
MyFirstContribution.txt MyFirstContribution: mention contrib/contacts/git-contacts 2024-04-18 14:55:09 -07:00
MyFirstObjectWalk.txt MyFirstObjectWalk: add stderr to pipe processing 2024-03-27 09:24:35 -07:00
ReviewingGuidelines.txt ReviewingGuidelines: encourage positive reviews more 2024-07-25 08:50:09 -07:00
SubmittingPatches Merge branch 'jt/doc-submitting-rerolled-series' into maint-2.45 2024-05-31 15:28:21 -07:00
ToolsForGit.txt
…
asciidoc.conf
…
asciidoctor-extensions.rb
…
blame-options.txt
…
build-docdep.perl
…
cat-texi.perl
…
cmd-list.perl
…
config.txt Merge branch 'tb/pseudo-merge-reachability-bitmap' 2024-06-24 16:39:13 -07:00
date-formats.txt Documentation: fix typos describing date format 2024-04-12 09:03:03 -07:00
diff-format.txt
…
diff-generate-patch.txt
…
diff-options.txt Merge branch 'jc/doc-diff-name-only' into maint-2.45 2024-06-28 15:53:14 -07:00
doc-diff
…
docbook-xsl.css
…
docbook.xsl
…
docinfo-html.in Doc: fix Asciidoctor css workaround 2024-07-23 11:02:52 -07:00
everyday.txto
…
fetch-options.txt doc: remote.*.skip{DefaultUpdate,FetchAll} stops prefetch 2024-09-09 10:06:13 -07:00
fix-texi.perl
…
fsck-msgids.txt fsck: add ref name check for files backend 2024-08-08 09:36:53 -07:00
git-add.txt add-patch: introduce 'p' in interactive-patch 2024-03-28 22:40:08 -07:00
git-am.txt Merge branch 'jk/am-retry' 2024-06-17 15:55:56 -07:00
git-annotate.txt
…
git-apply.txt apply: support --ours, --theirs, and --union for three-way merges 2024-09-09 10:07:24 -07:00
git-archimport.txt
…
git-archive.txt archive: document that --add-virtual-file takes full path 2024-06-26 12:56:45 -07:00
git-bisect-lk2009.txt
…
git-bisect.txt Merge branch 'jc/bisect-doc' into maint-2.43 2024-02-13 14:44:51 -08:00
git-blame.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-branch.txt branch: clarify <oldbranch> term 2024-01-08 10:06:05 -08:00
git-bugreport.txt bugreport.c: fix a crash in `git bugreport` with `--no-suffix` option 2024-03-16 09:31:42 -07:00
git-bundle.txt
…
git-cat-file.txt docs: explain the order of output in the batched mode of git-cat-file(1) 2024-08-22 14:59:22 -07:00
git-check-attr.txt
…
git-check-ignore.txt
…
git-check-mailmap.txt check-mailmap: add options for additional mailmap sources 2024-08-27 14:51:29 -07:00
git-check-ref-format.txt
…
git-checkout-index.txt
…
git-checkout.txt Merge branch 'jc/orphan-unborn' 2024-01-02 13:51:30 -08:00
git-cherry-pick.txt cherry-pick: add `--empty` for more robust redundant commit handling 2024-03-25 16:45:41 -07:00
git-cherry.txt
…
git-citool.txt
…
git-clean.txt clean: further clean-up of implementation around "--force" 2024-03-04 14:05:13 -08:00
git-clone.txt doc: git-clone fix discrepancy between asciidoc and asciidoctor 2024-07-20 16:24:12 -07:00
git-column.txt
…
git-commit-graph.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-commit-tree.txt
…
git-commit.txt doc: remove dangling closing parenthesis 2024-07-22 17:32:36 -07:00
git-config.txt Merge branch 'jc/config-doc-update' into maint-2.46 2024-09-13 15:26:52 -07:00
git-count-objects.txt
…
git-credential-cache--daemon.txt
…
git-credential-cache.txt
…
git-credential-store.txt
…
git-credential.txt credential: add method for querying capabilities 2024-04-16 22:39:08 -07:00
git-cvsexportcommit.txt
…
git-cvsimport.txt
…
git-cvsserver.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-daemon.txt doc: enforce placeholders in documentation 2023-12-26 11:06:57 -08:00
git-describe.txt
…
git-diagnose.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-diff-files.txt
…
git-diff-index.txt
…
git-diff-tree.txt Merge branch 'jc/grammo-fixes' into maint-2.46 2024-09-12 11:02:19 -07:00
git-diff.txt
…
git-difftool.txt Merge branch 'ps/difftool-dir-diff-exit-code' into HEAD 2024-03-01 14:38:54 -08:00
git-fast-export.txt doc: end sentences with full-stop 2024-02-20 15:03:13 -08:00
git-fast-import.txt Merge branch 'xx/rfc2822-date-format-in-doc' 2024-04-23 11:52:40 -07:00
git-fetch-pack.txt
…
git-fetch.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-filter-branch.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-fmt-merge-msg.txt
…
git-for-each-ref.txt for-each-ref: add 'is-base' token 2024-08-14 10:10:06 -07:00
git-for-each-repo.txt for-each-repo: optionally keep going on an error 2024-04-24 10:46:03 -07:00
git-format-patch.txt Merge branch 'jc/format-patch-more-aggressive-range-diff' 2024-05-28 11:17:10 -07:00
git-fsck-objects.txt
…
git-fsck.txt
…
git-fsmonitor--daemon.txt
…
git-gc.txt builtin/gc: add a `--detach` flag 2024-08-16 09:46:25 -07:00
git-get-tar-commit-id.txt
…
git-grep.txt grep docs: describe --no-index further and improve formatting a bit 2024-03-25 14:00:03 -07:00
git-gui.txt SubmittingPatches: welcome the new maintainer of git-gui part 2024-05-11 14:31:30 -07:00
git-hash-object.txt
…
git-help.txt
…
git-hook.txt
…
git-http-backend.txt
…
git-http-fetch.txt
…
git-http-push.txt
…
git-imap-send.txt
…
git-index-pack.txt index-pack: --fsck-objects to take an optional argument for fsck msgs 2024-02-01 11:09:53 -08:00
git-init-db.txt
…
git-init.txt doc: git-init: apply new documentation formatting guidelines 2024-03-29 10:57:40 -07:00
git-instaweb.txt
…
git-interpret-trailers.txt doc: fix some placeholders formating 2024-03-16 10:04:53 -07:00
git-log.txt
…
git-ls-files.txt doc: fix hex code escapes in git-ls-files 2024-07-26 10:53:21 -07:00
git-ls-remote.txt ls-remote: introduce --branches and deprecate --heads 2024-06-04 15:07:08 -07:00
git-ls-tree.txt
…
git-mailinfo.txt
…
git-mailsplit.txt
…
git-maintenance.txt doc: remote.*.skip{DefaultUpdate,FetchAll} stops prefetch 2024-09-09 10:06:13 -07:00
git-merge-base.txt
…
git-merge-file.txt
…
git-merge-index.txt
…
git-merge-one-file.txt
…
git-merge-tree.txt Documentation/git-merge-tree.txt: document -X 2024-05-07 15:36:08 -07:00
git-merge.txt Merge branch 'ml/doc-merge-updates' into maint-2.43 2024-02-08 16:22:10 -08:00
git-mergetool--lib.txt
…
git-mergetool.txt
…
git-mktag.txt
…
git-mktree.txt
…
git-multi-pack-index.txt midx: implement support for writing incremental MIDX chains 2024-08-06 12:01:39 -07:00
git-mv.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-name-rev.txt
…
git-notes.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-p4.txt
…
git-pack-objects.txt
…
git-pack-redundant.txt
…
git-pack-refs.txt builtin/pack-refs: introduce new "--auto" flag 2024-03-25 09:54:07 -07:00
git-patch-id.txt
…
git-prune-packed.txt
…
git-prune.txt
…
git-pull.txt doc: format alternatives in synopsis 2024-03-16 10:04:45 -07:00
git-push.txt
…
git-quiltimport.txt
…
git-range-diff.txt
…
git-read-tree.txt
…
git-rebase.txt Merge branch 'jc/doc-rebase-fuzz-vs-offset-fix' into maint-2.46 2024-08-16 12:50:55 -07:00
git-receive-pack.txt
…
git-reflog.txt builtin/reflog: introduce subcommand to list reflogs 2024-02-21 09:58:07 -08:00
git-refs.txt builtin/refs: add verify subcommand 2024-08-08 09:36:53 -07:00
git-remote-ext.txt
…
git-remote-fd.txt
…
git-remote-helpers.txto
…
git-remote.txt git-remote.txt: fix typo 2024-02-21 10:02:55 -08:00
git-repack.txt
…
git-replace.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-replay.txt Documentation: fix linkgit reference 2024-04-15 11:02:43 -07:00
git-request-pull.txt
…
git-rerere.txt
…
git-reset.txt
…
git-restore.txt
…
git-rev-list.txt
…
git-rev-parse.txt Merge branch 'jc/rev-parse-fatal-doc' into maint-2.45 2024-06-28 15:53:14 -07:00
git-revert.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
git-rm.txt
…
git-send-email.txt send-email: document --mailmap and associated configuration 2024-09-25 08:58:38 -07:00
git-send-pack.txt
…
git-sh-i18n--envsubst.txt
…
git-sh-i18n.txt
…
git-sh-setup.txt
…
git-shell.txt
…
git-shortlog.txt
…
git-show-branch.txt Merge branch 'ri/doc-show-branch-fix' 2024-07-15 10:11:43 -07:00
git-show-index.txt
…
git-show-ref.txt show-ref: introduce --branches and deprecate --heads 2024-06-04 15:07:08 -07:00
git-show.txt
…
git-sparse-checkout.txt
…
git-stage.txt
…
git-stash.txt
…
git-status.txt Merge branch 'jc/show-untracked-false' 2024-03-28 14:13:50 -07:00
git-stripspace.txt
…
git-submodule.txt builtin/submodule: allow "add" to use different ref storage format 2024-08-08 09:22:21 -07:00
git-svn.txt git-svn: mention `svn:global-ignores` in help+docs 2024-08-14 15:10:24 -07:00
git-switch.txt Merge branch 'jc/orphan-unborn' 2024-01-02 13:51:30 -08:00
git-symbolic-ref.txt
…
git-tag.txt builtin/tag: add --trailer option 2024-05-07 10:06:03 -07:00
git-tools.txt
…
git-unpack-file.txt
…
git-unpack-objects.txt
…
git-update-index.txt documentation: git-update-index: add --show-index-version to synopsis 2024-05-13 16:57:17 -07:00
git-update-ref.txt update-ref: add support for 'symref-update' command 2024-06-07 10:25:45 -07:00
git-update-server-info.txt
…
git-upload-archive.txt
…
git-upload-pack.txt Sync with 2.42.2 2024-04-19 12:38:50 +02:00
git-var.txt
…
git-verify-commit.txt
…
git-verify-pack.txt
…
git-verify-tag.txt
…
git-version.txt
…
git-web--browse.txt
…
git-whatchanged.txt
…
git-worktree.txt
…
git-write-tree.txt
…
git.txt advice: recommend GIT_ADVICE=0 for tools 2024-09-06 14:15:16 -07:00
gitattributes.txt Merge branch 'ss/doc-eol-attr-fix' 2024-07-08 14:53:08 -07:00
gitcli.txt doc: option value may be separate for valid reasons 2024-11-25 14:20:15 +09:00
gitcore-tutorial.txt
…
gitcredentials.txt doc: option value may be separate for valid reasons 2024-11-25 14:20:15 +09:00
gitcvs-migration.txt
…
gitdiffcore.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
giteveryday.txt
…
gitfaq.txt gitfaq: add entry about syncing working trees 2024-07-09 21:24:42 -07:00
gitformat-bundle.txt
…
gitformat-chunk.txt
…
gitformat-commit-graph.txt Documentation: fix typos 2024-09-23 12:47:36 -07:00
gitformat-index.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
gitformat-pack.txt
…
gitformat-signature.txt
…
gitglossary.txt
…
githooks.txt Merge branch 'jt/doc-post-receive-hook-update' into maint-2.46 2024-08-16 12:50:53 -07:00
gitignore.txt
…
gitk.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
gitmailmap.txt
…
gitmodules.txt
…
gitnamespaces.txt
…
gitpacking.txt Documentation/gitpacking: make sample configs listing blocks 2024-07-17 08:48:30 -07:00
gitprotocol-capabilities.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
gitprotocol-common.txt
…
gitprotocol-http.txt Merge branch 'js/update-urls-in-doc-and-comment' into maint-2.43 2024-02-08 16:22:01 -08:00
gitprotocol-pack.txt
…
gitprotocol-v2.txt upload-pack: accept only a single packfile-uri line 2024-02-28 14:42:01 -08:00
gitremote-helpers.txt Merge branch 'jk/remote-helper-object-format-option-fix' 2024-04-03 10:56:18 -07:00
gitrepository-layout.txt
…
gitrevisions.txt
…
gitsubmodules.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
gittutorial-2.txt
…
gittutorial.txt Merge branch 'jc/grammo-fixes' into maint-2.46 2024-09-12 11:02:19 -07:00
gitweb.conf.txt Merge branch 'js/update-urls-in-doc-and-comment' into maint-2.43 2024-02-08 16:22:01 -08:00
gitweb.txt Documentation: fix typos 2024-09-23 12:47:36 -07:00
gitworkflows.txt
…
glossary-content.txt Merge branch 'ps/pseudo-ref-terminology' 2024-07-18 08:30:26 -07:00
howto-index.sh
…
i18n.txt
…
install-doc-quick.sh
…
install-webdoc.sh
…
line-range-format.txt
…
line-range-options.txt
…
lint-fsck-msgids.perl
…
lint-gitlink.perl
…
lint-man-end-blurb.perl
…
lint-man-section-order.perl
…
lint-manpages.sh Documentation/lint-manpages: bubble up errors 2024-06-06 08:20:51 -07:00
manpage-bold-literal.xsl
…
manpage-normal.xsl
…
manpage.xsl
…
merge-options.txt
…
merge-strategies.txt
…
object-format-disclaimer.txt
…
pretty-formats.txt Merge branch 'bl/doc-key-val-sep-fix' 2024-03-25 16:16:35 -07:00
pretty-options.txt
…
pull-fetch-param.txt
…
ref-reachability-filters.txt
…
ref-storage-format.txt refs: introduce reftable backend 2024-02-07 08:28:37 -08:00
rerere-options.txt
…
rev-list-description.txt
…
rev-list-options.txt Merge branch 'ja/doc-formatting-fix' 2024-03-25 16:16:34 -07:00
revisions.txt
…
scalar.txt scalar: add --no-tags option to 'scalar clone' 2024-09-06 14:13:48 -07:00
sequencer.txt
…
signoff-option.txt
…
texi.xsl
…
trace2-target-values.txt doc: enforce dashes in placeholders 2023-12-26 11:06:55 -08:00
transfer-data-leaks.txt
…
urls-remotes.txt
…
urls.txt doc: git-clone: apply new documentation formatting guidelines 2024-03-29 10:57:40 -07:00
user-manual.conf
…
user-manual.txt Documentation/user-manual.txt: example for generating object hashes 2024-03-12 13:32:11 -07:00