Avoids invalid sample e-mail addresses from becoming mailto links
in the formatted output.
* jk/avoid-mailto-invalid-in-doc:
Documentation: don't link to example mail addresses
It might be a better idea to move the text the bottom one adds to
the extended description from the quick checklist part.
* as/doc-for-devs:
Documentation: move support for old compilers to CodingGuidelines
SubmittingPatches: add convention of prefixing commit messages
"git fetch --tags" was explained as if it were "git fetch
--no-no-tags", which is not the case, causing confusion.
* jc/fetch-tags-doc:
fetch --tags: clarify documentation
* sl/git-svn-docs:
git-svn: Note about tags.
git-svn: Expand documentation for --follow-parent
git-svn: Recommend use of structure options.
git-svn: Document branches with at-sign(@).
The contents of this document does not describe any particular API, but
is more about the way to add a new command, which belongs to the "How To"
section of the documentation suite.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Git takes pathspec arguments in many places to limit the
scope of an operation. These pathspecs are treated not as
literal paths, but as glob patterns that can be fed to
fnmatch. When a user is giving a specific pattern, this is a
nice feature.
However, when programatically providing pathspecs, it can be
a nuisance. For example, to find the latest revision which
modified "$foo", one can use "git rev-list -- $foo". But if
"$foo" contains glob characters (e.g., "f*"), it will
erroneously match more entries than desired. The caller
needs to quote the characters in $foo, and even then, the
results may not be exactly the same as with a literal
pathspec. For instance, the depth checks in
match_pathspec_depth do not kick in if we match via fnmatch.
This patch introduces a global command-line option (i.e.,
one for "git" itself, not for specific commands) to turn
this behavior off. It also has a matching environment
variable, which can make it easier if you are a script or
porcelain interface that is going to issue many such
commands.
This option cannot turn off globbing for particular
pathspecs. That could eventually be done with a ":(noglob)"
magic pathspec prefix. However, that level of granularity is
more cumbersome to use for many cases, and doing ":(noglob)"
right would mean converting the whole codebase to use
"struct pathspec", as the usual "const char **pathspec"
cannot represent extra per-item flags.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This allows you to easily record a submodule.<name>.branch option in
.gitmodules when you add a new submodule. With this patch,
$ git submodule add -b <branch> <repository> [<path>]
$ git config -f .gitmodules submodule.<path>.branch <branch>
reduces to
$ git submodule add -b <branch> <repository> [<path>]
This means that future calls to
$ git submodule update --remote ...
will get updates from the same branch that you used to initialize the
submodule, which is usually what you want.
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The current `update` command incorporates the superproject's gitlinked
SHA-1 ($sha1) into the submodule HEAD ($subsha1). Depending on the
options you use, it may checkout $sha1, rebase the $subsha1 onto
$sha1, or merge $sha1 into $subsha1. This helps you keep up with
changes in the upstream superproject.
However, it's also useful to stay up to date with changes in the
upstream subproject. Previous workflows for incorporating such
changes include the ungainly:
$ git submodule foreach 'git checkout $(git config --file $toplevel/.gitmodules submodule.$name.branch) && git pull'
With this patch, all of the useful functionality for incorporating
superproject changes can be reused to incorporate upstream subproject
updates. When you specify --remote, the target $sha1 is replaced with
a $sha1 of the submodule's origin/master tracking branch. If you want
to merge a different tracking branch, you can configure the
`submodule.<name>.branch` option in `.gitmodules`. You can override
the `.gitmodules` configuration setting for a particular superproject
by configuring the option in that superproject's default configuration
(using the usual configuration hierarchy, e.g. `.git/config`,
`~/.gitconfig`, etc.).
Previous use of submodule.<name>.branch
=======================================
Because we're adding a new configuration option, it's a good idea to
check if anyone else is already using the option. The foreach-pull
example above was described by Ævar in
commit f030c96d86
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Fri May 21 16:10:10 2010 +0000
git-submodule foreach: Add $toplevel variable
Gerrit uses the same interpretation for the setting, but because
Gerrit has direct access to the subproject repositories, it updates
the superproject repositories automatically when a subproject changes.
Gerrit also accepts the special value '.', which it expands into the
superproject's branch name.
Although the --remote functionality is using `submodule.<name>.branch`
slightly differently, the effect is the same. The foreach-pull
example uses the option to record the name of the local branch to
checkout before pulls. The tracking branch to be pulled is recorded
in `.git/modules/<name>/config`, which was initialized by the module
clone during `submodule add` or `submodule init`. Because the branch
name stored in `submodule.<name>.branch` was likely the same as the
branch name used during the initial `submodule add`, the same branch
will be pulled in each workflow.
Implementation details
======================
In order to ensure a current tracking branch state, `update --remote`
fetches the submodule's remote repository before calculating the
SHA-1. However, I didn't change the logic guarding the existing fetch:
if test -z "$nofetch"
then
# Run fetch only if $sha1 isn't present or it
# is not reachable from a ref.
(clear_local_git_env; cd "$path" &&
( (rev=$(git rev-list -n 1 $sha1 --not --all 2>/dev/null) &&
test -z "$rev") || git-fetch)) ||
die "$(eval_gettext "Unable to fetch in submodule path '\$path'")"
fi
There will not be a double-fetch, because the new $sha1 determined
after the `--remote` triggered fetch should always exist in the
repository. If it doesn't, it's because some racy process removed it
from the submodule's repository and we *should* be re-fetching.
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As it was not a common operation, it was described as if it is a
side note for the more common two-commit variant, but this mode
behaves very differently, e.g. it does not make any sense to ask
recursive behaviour, or give the command a pathspec.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the behavior implemented in 70c9ac2 (DWIM "git checkout
frotz" to "git checkout -b frotz origin/frotz").
Signed-off-by: Chris Rorvick <chris@rorvick.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The forms of checkout that do not take a path are lumped together in
the DESCRIPTION section, but the description for this group is
dominated by explanation of the -b|-B form.
Split these apart for more clarity.
Signed-off-by: Chris Rorvick <chris@rorvick.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Traditionally, %C(color attr) always emitted the ANSI color
sequence; it was up to the scripts that wanted to conditionally
color their output to omit %C(...) specifier when they do not want
colors.
Optionally allow "auto," to be prefixed to the color, so that the
output is colored iff we would color regular "log" output
(e.g., taking into account color.* and --color command line
options).
Tests and pretty_context bits by Jeff King <peff@peff.net>.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "Try to be nice to older C compilers" text is clearly a guideline
to be borne in mind whilst coding rather than when submitting patches.
Signed-off-by: Adam Spiers <git@adamspiers.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Conscientious newcomers to git development will read SubmittingPatches
and CodingGuidelines, but could easily miss the convention of
prefixing commit messages with a single word identifying the file
or area the commit touches.
Signed-off-by: Adam Spiers <git@adamspiers.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Email addresses in documentation are converted into mailto: hyperlinks
in the HTML output and footnotes in man pages. This isn't desirable for
cases where the address is used as an example and is not valid.
Particularly annoying is the example "jane@laptop.(none)" which appears
in git-shortlog(1) as "jane@laptop[1].(none)", with note 1 saying:
1. jane@laptop
mailto:jane@laptop
Fix this by escaping these email addresses with a leading backslash, to
prevent Asciidoc expanding them as inline macros.
In the case of mailmap.txt, render the address monospaced so that it
matches the block examples surrounding that paragraph.
Helped-by: Jeff King <peff@peff.net>
Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Start list with 1 instead of 0; ASCIIDOC will renumber it anyway.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Explain that --tags is just like another explicit refspec on the
command line and as such overrides the default refspecs configured
via the remote.$name.fetch variable.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Unlike other environment variables (e.g. GIT_WORK_TREE, GIT_NAMESPACE),
the Documentation/git.txt file did not mention that the GIT_DIR
environment variable can also be set using the --git-dir command line
option.
Signed-off-by: Manlio Perillo <manlio.perillo@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The motivation for mailmap.blob is to let users of bare
repositories use the mailmap feature, as they would not have
a checkout containing the .mailmap file. We can make it even
easier for them by just looking in HEAD:.mailmap by default.
We can't know for sure that this is where they would keep a
mailmap, of course, but it is the best guess (and it matches
the non-bare behavior, which reads from HEAD:.mailmap in the
working tree). If it's missing, git will silently ignore the
setting.
We do not do the same magic in the non-bare case, because:
1. In the common case, HEAD:.mailmap will be the same as
the .mailmap in the working tree, which is a no-op.
2. In the uncommon case, the user has modified .mailmap
but not yet committed it, and would expect the working
tree version to take precedence.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Anywhere we mention mailmap.file, it is probably worth
mentioning mailmap.blob, as well.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A cache-tree entry with a negative entry count is considered invalid
by the current Git; it records that we do not know the object name
of a tree that would result by writing the directory covered by the
cache-tree as a tree object.
Clarify that any entry with a negative entry count is invalid, but
the implementations must write -1 there. This way, we can later
decide to allow writers to use negative values other than -1 to
encode optional information on such invalidated entries without
harming interoperability; we do not know what will be encoded and
how, so we keep these other negative values as reserved for now.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We earlier removed a link to list of contributors that pointed to a
defunct page; let's use a working one from Ohloh.net to replace it
instead.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In a bare repository, there isn't a simple way to respect an
in-tree mailmap without extracting it to a temporary file.
This patch provides a config variable, similar to
mailmap.file, which reads the mailmap from a blob in the
repository.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
Git 1.8.0.2
Documentation/git-stash.txt: add a missing verb
git(1): remove a defunct link to "list of authors"
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The linked page has not been showing the promised "more complete
list" for more than 6 months by now, and nobody has resurrected
the list there nor elsewhere since then.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The line that happens to begin with indent followed by "3. " was
interpreted as if it was an enumerated list; just wrap the lines
differently to work it around for now.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation was misleading in that it gave the impression that
'for-push' could be used as a ref attribute in the output of the
'list' command. That is wrong.
Also, explicitly point out the connection between the commands
'list' and 'options' on the one hand, and the sections
'REF LIST ATTRIBUTES' and 'OPTIONS' on the other hand.
Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In particular, document 'list for-push' separately from 'list', as
the former needs only be supported for the push/export
capabilities, and the latter only for fetch/import. Indeed, a
hypothetically 'push-only' helper would only need to support the
former, not the latter.
Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This also remove some duplication in the descriptions
(e.g. refspec was explained twice with similar level of detail).
Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Specifically, document the 'export' and '(im|ex)port-marks'
capabilities as well as the export command, which were
undocumented (but in active use).
Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In the distant past, the order things were documented was
'Invocation', 'Commands', 'Capabilities', ...
Then it was decided that before giving a list of Commands, there
should be an overall description of the 'Input format', which was
a wise decision. However, this description was put as the very
first thing, with the rationale that any implementor would want
to know that first.
However, it seems an implementor would actually first need to
know how the remote helper will be invoked, so moving
'Invocation' to the front again seems logical. Moreover, we now
don't switch from discussing the input format to the invocation
style and then back to input related stuff.
Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document that when using git svn, one should usually either use the
directory structure options to import branches as branches, or only
import one subdirectory. The default behaviour of cloning all branches
and tags as subdirectories in the working copy is usually not what the
user wants.
Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
Acked-by: Eric Wong <normalperson@yhbt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git svn sometimes creates branches with an at-sign in the name
(branchname@revision). These branches confuse many users and it is a FAQ
why they are created. Document when git svn creates them.
Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
Acked-by: Eric Wong <normalperson@yhbt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
