The "git clone" documentation refers to command line options in its
description in the short form; they have been replaced with long
forms to make them more recognisable.
* qn/clone-doc-use-long-form:
docs: git-clone: list short form of options first
docs: git-clone: refer to long form of options
The description about slashes in gitignore patterns (used to
indicate things like "anchored to this level only" and "only
matches directories") has been revamped.
* an/ignore-doc-update:
gitignore.txt: make slash-rules more readable
"git merge --squash" is designed to update the working tree and the
index without creating the commit, and this cannot be countermanded
by adding the "--commit" option; the command now refuses to work
when both options are given.
* vv/merge-squash-with-explicit-commit:
merge: refuse --commit with --squash
The gpg --verify usage example within the 'gpg.program' variable
reference provides an incorrect example of the gpg --verify command
arguments.
The command argument order, when providing both a detached signature
and data, should be signature first and data second:
https://gnupg.org/documentation/manuals/gnupg/Operational-GPG-Commands.html
Signed-off-by: Robert Morgan <robert.thomas.morgan@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Correct the api-trace2 documentation, which lists "signal" as an
expected field for the signal event type, but which actually outputs
"signo" as the field name.
Signed-off-by: Josh Steadmon <steadmon@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
List the short form of options (e.g.: '-l') before the long form (e.g.
'--local').
This is to match the doc of git-add, git-commit, git-clean, git-branch...
Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
To make the doc of git-clone easier to read,
refer to the long form of the options
(it is easier to guess what '--verbose' is doing than '-v').
Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It's been behaving so since 6a536e2076 (git: treat "git -C '<path>'"
as a no-op when <path> is empty, 2015-03-06).
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git.kernel.org uses cgit, not gitweb, these days:
$ w3m -dump 'http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb' | grep -w generated
generated by cgit 1.2-0.3.lf.el7 (git 2.18.0) at 2019-06-22 16:14:38 +0000
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
One can see that an alias that begins with a non-command first word,
such as `loud-rebase = -c commit.verbose=true rebase`, is permitted.
However, this isn't immediately obvious to users as alias instances
typically begin with a command.
Document the fact that an alias can begin with a non-command first word
so that users will be able to discover that this is a feature.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Before, the documentation would mix " and ' for code and config
snippets. Change these instances to ` so that they are marked up in
monospace.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Renew paragraphs relevant for pattern with slash.
Aim to make it more clear and to avoid possible
pitfalls for the reader. Add some examples.
Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Disable "--filter=sparse:path=<path>" that would allow reading from
paths on the filesystem.
* cc/list-objects-filter-wo-sparse-path:
list-objects-filter: disable 'sparse:path' filters
Improve and complete the list of required email related Perl modules,
clarifying which are core Perl modules and remove Net::SMTP::SSL.
git-send-email uses the TLS support in the Net::SMTP core module from
recent versions of Perl. Documenting the minimum version is complex
because of separate numbering for Perl (5.21.5~169), Net:SMTP (2.34)
and libnet (3.01). Version numbers from commit:
bfbfc9a953 ("send-email: Net::SMTP::starttls was introduced in v2.34",
2017-05-31).
Users of older Perl versions without Net::SMTP::SSL installed will get a
clear error message.
Signed-off-by: Chris Mayo <aklhfex@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A bit more leftover clean-up to deprepcate "rebase -p".
* js/rebase-deprecate-preserve-merges:
rebase docs: recommend `-r` over `-p`
docs: say that `--rebase=preserve` is deprecated
tests: mark a couple more test cases as requiring `rebase -p`
If someone wants to use as a filter a sparse file that is in the
repository, something like "--filter=sparse:oid=<ref>:<path>"
already works.
So 'sparse:path' is only interesting if the sparse file is not in
the repository. In this case though the current implementation has
a big security issue, as it makes it possible to ask the server to
read any file, like for example /etc/password, and to explore the
filesystem, as well as individual lines of files.
If someone is interested in using a sparse file that is not in the
repository as a filter, then at the minimum a config option, such
as "uploadpack.sparsePathFilter", should be implemented first to
restrict the directory from which the files specified by
'sparse:path' can be read.
For now though, let's just disable 'sparse:path' filters.
Helped-by: Matthew DeVore <matvore@google.com>
Helped-by: Jeff Hostetler <git@jeffhostetler.com>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The availability of these pattern selections is not obvious from
the man pages, as per mail thread <87lfz3vcbt.fsf@evledraar.gmail.com>.
Provide examples.
Re-order the `git branch` synopsis to emphasise the `--list <pattern>`
pairing. Also expand and reposition the `all/remotes` options.
Split the over-long description into three parts so that the <pattern>
description can be seen.
Clarify that the `all/remotes` options require the --list if patterns
are to be used.
Add examples of listing remote tracking branches that match a pattern,
including `git for-each-ref` which has more options.
Improve the -a/-r warning message. The message confused this author
as the combined -a and -r options had not been given, though a pattern
had. Specifically guide the user that maybe they needed the --list
option to enable a remote branch pattern selection.
Signed-off-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We check for a handy environment variable GIT_DEBUGGER when running via
bin-wrappers/, but this feature is undocumented. Add a hint to how to
use it into the CodingGuidelines (which is where other useful
environment settings like DEVELOPER are documented).
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The `--preserve-merges` option is now deprecated in favor of
`--rebase-merges`; Let's stop recommending the former.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As of Git v2.22.0, the `--preserve-merges` backend of `git rebase` will
be officially deprecated in favor of the `--rebase-merges` backend.
Consequently, `git pull --rebase=preserve` will also be deprected. State
this explicitly.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Convert option_commit to tristate, representing the states of
'default/untouched', 'enabled-by-cli', 'disabled-by-cli'. With this in
place, check whether option_commit was enabled by cli when squashing a
merge. If so, error out, as this is not supported.
Previously, when --squash was supplied, 'option_commit' was silently
dropped. This could have been surprising to a user who tried to override
the no-commit behavior of squash using --commit explicitly.
Add a note to the --squash option for git-merge to clarify the
incompatibility, and add a test case to t7600-merge.sh
Cc: Junio C Hamano <gitster@pobox.com>
Cc: Rafael Ascensão <rafa.almas@gmail.com>
Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: Vishal Verma <vishal@stellar.sh>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove a reference to git-cvsimport in the intro. As can be seen from
the history of this command[1] it was originally intended for use with
git-cvsimport, but how it uses it (and that it uses it at all) is
irrelevant trivia at this point.
1. See 7672db20c2 ("[PATCH] Expose object ID computation functions.",
2005-07-08) and 8b8840e046 ("[PATCH] cvsgit fixes: spaces in
filenames and CVS server dialog woes", 2005-08-15).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The descriptions of the GIT_TRACE2* environment variables link to the
technical docs for further details on the supported values. However,
a link like this only really works if the docs are viewed in a browser
and the full documentation is available. OTOH, in 'man git' there are
no links to conveniently click on, and distro-shipped git packages
tend to include only the man pages, while the technical docs and the
docs in html format are in a separate 'git-doc' package.
So let's describe the supported values to make the manpage more
self-contained, but still keep the references to the technical docs
because the details of the SID, and the JSON and perf output formats
are definitely beyond the scope of 'man git'.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For an environment variable that is supposed to be set by users, the
GIT_TR2* env vars are just too unclear, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use
abbreviations, and in case of the few that do (GIT_DIR,
GIT_COMMON_DIR, GIT_DIFF_OPTS) it's quite obvious what the
abbreviations (DIR and OPTS) stand for. But what does TR stand for?
Track, traditional, trailer, transaction, transfer, transformation,
transition, translation, transplant, transport, traversal, tree,
trigger, truncate, trust, or ...?!
The trace2 facility, as the '2' suffix in its name suggests, is
supposed to eventually supercede Git's original trace facility. It's
reasonable to expect that the corresponding environment variables
follow suit, and after the original GIT_TRACE variables they are
called GIT_TRACE2; there is no such thing is 'GIT_TR'.
All trace2-specific config variables are, very sensibly, in the
'trace2' section, not in 'tr2'.
OTOH, we don't gain anything at all by omitting the last three
characters of "trace" from the names of these environment variables.
So let's rename all GIT_TR2* environment variables to GIT_TRACE2*,
before they make their way into a stable release.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
There appears to be a bug in the toolchain generating manpages from
lettered lists. When a list is enumerated with letters, the resulting
nroff shows numbers instead. Mostly this is harmless, but in the case of
gitsubmodules, the paragraph following the list refers back to each
bullet by letter. As a result, reading this documentation via `man
gitsubmodules` is hard to parse - readers must infer that a bug exists
and a refers to 1, b refers to 2, and c refers to 3 in the list above.
The problem specifically was introduced in ad47194; previously rather
than generating numerated lists the bulleted area was entirely
monospaced in HTML and shown in plaintext in nroff.
The bug seems to exist in docbook-xml - I've reported it on May 1 via
the docbook-apps mail list - but for now it may make more sense to just
work around the issue.
Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Update "git difftool" and "git mergetool" so that the combinations
of {diff,merge}.{tool,guitool} configuration variables serve as
fallback settings of each other in a sensible order.
* dl/difftool-mergetool:
difftool: fallback on merge.guitool
difftool: make --gui, --tool and --extcmd mutually exclusive
mergetool: fallback to tool when guitool unavailable
mergetool--lib: create gui_mode function
mergetool: use get_merge_tool function
t7610: add mergetool --gui tests
t7610: unsuppress output
"git branch new A...B" and "git checkout -b new A...B" have been
taught that in their contexts, the notation A...B means "the merge
base between these two commits", just like "git checkout A...B"
detaches HEAD at that commit.
* dl/branch-from-3dot-merge-base:
branch: make create_branch accept a merge base rev
t2018: cleanup in current test
The stash.useBuiltin variable introduced in 90a462725e ("stash:
optionally use the scripted version again", 2019-02-25) was turned on by
default, but had no documentation.
Let's document it so that users who run into any stability issues with
the C rewrite know there's an escape hatch, and spell out that the
user should please report the bug when they have to turn off the
built-in stash.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Docfix.
* dl/rev-tilde-doc-clarify:
revisions.txt: remove ambibuity between <rev>:<path> and :<path>
revisions.txt: mention <rev>~ form
revisions.txt: mark optional rev arguments with []
revisions.txt: change "rev" to "<rev>"
The connectivity bitmaps are created by default in bare
repositories now; also the pathname hash-cache is created by
default to avoid making crappy deltas when repacking.
* ew/repack-with-bitmaps-by-default:
pack-objects: default to writing bitmap hash-cache
t5310: correctly remove bitmaps for jgit test
repack: enable bitmaps by default on bare repos
Polishing of the new trace2 facility continues. The system-level
configuration can specify site-wide trace2 settings, which can be
overridden with per-user configuration and environment variables.
* jh/trace2-sid-fix:
trace2: fixup access problem on /etc/gitconfig in read_very_early_config
trace2: update docs to describe system/global config settings
trace2: make SIDs more unique
trace2: clarify UTC datetime formatting
trace2: report peak memory usage of the process
trace2: use system/global config for default trace2 settings
config: add read_very_early_config()
trace2: find exec-dir before trace2 initialization
trace2: add absolute elapsed time to start event
trace2: refactor setting process starting time
config: initialize opts structure in repo_read_config()
