Git has an additional "commit graph" capability that supplements the
normal commit object's directed acyclic graph (DAG). The supplemental
commit graph file is designed for speed of access.
Describe the commit graph both from the normative DAG view point and
from the commit graph file perspective.
Also, clarify the link between the branch ref and branch tip
by linking to the `ref` glossary entry, matching this commit graph
entry.
The commit-graph file is also distinguished by its hyphenation.
Subsequent commit catches the few cases where the hyphenation of
commit-graph was missing.
Signed-off-by: Philip Oakley <philipoakley@iee.email>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
The abbreviation 'ODB' is used in the technical documentation
sections for commit-graph and parallel-checkout, along with an
'odb' option in `git-pack-redundant`, without expansion.
Use 'object database' in full, in those entries. The text has not
been reflowed to keep the changes minimal.
While in the glossary for `object` terms, add the common`oid`
abbreviation to its entry.
Signed-off-by: Philip Oakley <philipoakley@iee.email>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
We have description on "per worktree ref", but "worktree" is not
described in the glossary. We do have "working tree", though.
Casually put, a "working tree" is what your editor and compiler
interacts with. "worktree" is a mechanism to allow one or more
"working tree"s to be attached to a repository and used to check out
different commits and branches independently, which includes not
just a "working tree" but also repository metadata like HEAD, the
index to support simultaneous use of them. Historically, we used
these terms interchangeably but we have been trying to use "working
tree" when we mean it, instead of "worktree".
Most of the existing references to "working tree" in the glossary do
refer primarily to the working tree portion, except for one that
said refs like HEAD and refs/bisect/* are per "working tree", but it
is more precise to say they are per "worktree".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The text was somewhat confusing between the revision itself and the author.
Signed-off-by: Reuven Yagel <robi@post.jce.ac.il>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The old phrasing is at least questionable, if not wrong, as there are
a lot of branches out there that didn't see active development for
years, yet they are still branches, ready to become active again any
time.
Signed-off-by: Sergey Organov <sorganov@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"Can not" suggests one has the option to not do something, whereas
"cannot" more strongly suggests something is disallowed or impossible.
Noticed "can not", mistakenly used instead of "cannot" in git help
glossary, then ran git grep 'can not' and found many other instances.
Only files in the Documentation folder were modified.
'Can not' also occurs in some source code comments and some test
assertion messages, and there is an error message and translation "can
not move directory into itself" which I may fix and submit separately
from the documentation change.
Also noticed and fixed "is does" in git help fetch, but there are no
other occurrences of that typo according to git grep.
Signed-off-by: Mark Rushakoff <mark.rushakoff@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add a definition for what overlay means in the context of git, to
clarify the recently introduced overlay-mode in git checkout.
Helped-by: Elijah Newren <newren@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This lets us use :(attr) with "git grep <tree-ish>" or "git log".
:(attr) requires another round of checking before we can declare that
a path is matched. This is done after path matching since we have lots
of optimization to take a shortcut when things don't match.
Note that if :(attr) is present, we can't return
all_entries_interesting / all_entries_not_interesting anymore because
we can't be certain about that. Not until match_pathspec_attrs() can
tell us "yes all these paths satisfy :(attr)".
Second note. Even though we walk a specific tree, we use attributes
from _worktree_ (or falling back to the index), not from .gitattributes
files on that tree. This by itself is not necessarily wrong, but the
user just have to be aware of this.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Ville Skyttä <ville.skytta@iki.fi>
Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even though "direct ancestor" is not defined in the glossary, the
common meaning of the term is simply "parent", parents being the only
direct ancestors, and the rest of ancestors being indirect ancestors.
As "parent" is obviously wrong in this place in the description, we
should simply say "ancestor", as everywhere else.
Signed-off-by: Sergey Organov <sorganov@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The ability to exclude paths with a negative pathspec is not mentioned
in the man pages for git grep and other commands where it might be
useful.
Add an example and a pointer to the pathspec glossary entry in the man
page for git grep to help the user to discover this ability.
Add similar pointers from the git-add and git-status man pages.
Additionally,
- Add a test for the behaviour when multiple exclusions are present.
- Add a test for the ^ alias.
- Improve name of existing test.
- Improve grammar in glossary description of the exclude pathspec.
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Manav Rathi <mnvrth@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The pathspec mechanism is extended via the new
":(attr:eol=input)pattern/to/match" syntax to filter paths so that it
requires paths to not just match the given pattern but also have the
specified attrs attached for them to be chosen.
Based on a patch by Stefan Beller <sbeller@google.com>
Signed-off-by: Brandon Williams <bmwill@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Instead of erroring out and telling the user that they should add a
positive pattern that covers everything else, just _do_ that.
For commands where we honor the current cwd by default (ie grep, ls-files
etc), we make that default positive pathspec be the current working
directory. And for commands that default to the whole project (ie diff,
log, etc), the default positive pathspec is the whole project.
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The choice of '!' for a negative pathspec ends up not only not matching
what we do for revisions, it's also a horrible character for shell
expansion since it needs quoting.
So add '^' as an alternative alias for an excluding pathspec entry.
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Drop a few old "todo" items by deciding that the change one of them
suggests is not such a good idea, and doing the change the other
one suggested to do.
* ss/user-manual:
user-manual: add addition gitweb information
user-manual: add section documenting shallow clones
glossary: define the term shallow clone
user-manual: remove temporary branch entry from todo list
There are several places in the documentation that
the term shallow clone is used. Defining the term
enables its use elsewhere with a known definition.
Signed-off-by: Stephen P. Smith <ischis2@cox.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We need the place we stick refs for bisects in progress to not be
shared between worktrees. So we make the refs/bisect/ hierarchy
per-worktree.
The is_per_worktree_ref function and associated docs learn that
refs/bisect/ is per-worktree, as does the git_path code in path.c
The ref-packing functions learn that per-worktree refs should not be
packed (since packed-refs is common rather than per-worktree).
Since refs/bisect is per-worktree, logs/refs/bisect should be too.
Signed-off-by: David Turner <dturner@twopensource.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add glossary entries for both concepts.
Pseudorefs and per-worktree refs do not yet have special handling,
because the files refs backend already handles them correctly. Later,
we will make the LMDB backend call out to the files backend to handle
per-worktree refs.
Signed-off-by: David Turner <dturner@twopensource.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Noticed-by: Philip Oakley <philipoakley@iee.org>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In addition to fixing trivial and obvious typos, be careful about
the following points:
- Spell ASCII, URL and CRC in ALL CAPS;
- Spell Linux as Capitalized;
- Do not omit periods in "i.e." and "e.g.".
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Re-word the section on "Updating a repository with git fetch" in the
user manual.
Various other minor fixes in the manual and glossary.
Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"**" means bold in ASCIIDOC, so we need to escape it. This is similar
to 8447dc8 (gitignore.txt: fix documentation of "**" patterns -
2013-11-07)
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We liberally use "committish" and "commit-ish" (and "treeish" and
"tree-ish"); as these are non-words, let's unify these terms to
their dashed form. More importantly, clarify the documentation on
object peeling using these terms.
* rh/ishes-doc:
glossary: fix and clarify the definition of 'ref'
revisions.txt: fix and clarify <rev>^{<type>}
glossary: more precise definition of tree-ish (a.k.a. treeish)
use 'commit-ish' instead of 'committish'
use 'tree-ish' instead of 'treeish'
glossary: define commit-ish (a.k.a. committish)
glossary: mention 'treeish' as an alternative to 'tree-ish'
A tree-ish isn't a ref. Also, mention dereferencing, and that a
commit dereferences to a tree, to support gitrevisions(7) and
rev-parse's error messages.
Signed-off-by: Richard Hansen <rhansen@bbn.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation contains a mix of the two spellings, so include both
in the glossary so that a search for either will lead to the
definition.
Signed-off-by: Richard Hansen <rhansen@bbn.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
:(glob)path differs from plain pathspec that it uses wildmatch with
WM_PATHNAME while the other uses fnmatch without FNM_PATHNAME. The
difference lies in how '*' (and '**') is processed.
With the introduction of :(glob) and :(literal) and their global
options --[no]glob-pathspecs, the user can:
- make everything literal by default via --noglob-pathspecs
--literal-pathspecs cannot be used for this purpose as it
disables _all_ pathspec magic.
- individually turn on globbing with :(glob)
- make everything globbing by default via --glob-pathspecs
- individually turn off globbing with :(literal)
The implication behind this is, there is no way to gain the default
matching behavior (i.e. fnmatch without FNM_PATHNAME). You either get
new globbing or literal. The old fnmatch behavior is considered
deprecated and discouraged to use.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Fix a typo ("remote remote-tracking") going back to the big cleanup
in 2010 (8b3f3f84 etc). Also, remove some more occurrences of
"tracking" and "remote tracking" in favor of "remote-tracking".
Signed-off-by: Michael Schubert <mschub@elegosoft.com>
Reviewed-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* jh/checkout-auto-tracking:
glossary: Update and rephrase the definition of a remote-tracking branch
branch.c: Validate tracking branches with refspecs instead of refs/remotes/*
t9114.2: Don't use --track option against "svn-remote"-tracking branches
t7201.24: Add refspec to keep --track working
t3200.39: tracking setup should fail if there is no matching refspec.
checkout: Use remote refspecs when DWIMming tracking branches
t2024: Show failure to use refspec when DWIMming remote branch names
t2024: Add tests verifying current DWIM behavior of 'git checkout <branch>'
The wording for "revision" in the glossary wanted to say it refers
to "commit (noun) as a concept" but it was badly phrased.
This may need further updates to hint that in contexts where it is
clear, the word may refer to an object name, not necessarily a
commit. But the patch as-is is already an improvement.
* jn/glossary-revision:
glossary: a revision is just a commit
The current definition of 'revision' sounds like it is saying that a
revision is a tree object. In reality it is just a commit.
This should be especially useful for people used to other revision
control systems trying to see how familiar concepts translate into git
terms.
Reported-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* ta/glossary:
glossary: improve definitions of refspec and pathspec
The name of the hash function is "SHA-1", not "SHA1"
glossary: improve description of SHA-1 related topics
glossary: remove outdated/misleading/irrelevant entries
The definition of a remote-tracking branch in the glossary have been
out-of-date for a while (by e.g. referring to "Pull:" from old-style
$GIT_DIR/remotes files).
Also, the preceding patches have formalized that a remote-tracking branch
must match a configured refspec in order to be usable as an upstream.
This patch rewrites the paragraph on remote-tracking branches accordingly.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The exact definition of "refspec" can be found in git-fetch and
git-push manpages. So don't duplicate this here in the glossary.
Actually the definition of "pathspec" should be moved to a separate
file akin to the way it's done with "refspec". But this will only be
wortwhile when there's more to say about it. So for the time being
just improve the first sentence a little bit; fix the indentation of
the first paragraph after the bullet list and remove the one-item
list of magic signatures with its - for the user - unnecessary
introduction of "magic word 'top'".
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The name of the hash function is "SHA-1", not "SHA1".
Also to people who look up "object name" in the glossary,
the details of which hash function is applied on what to
compute "object name" is not important but the fact that the
name is meant to be an unique identifier for the contents
stored in the object is.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When we introduced the concept of "detached HEAD", we made sure that
commands that operate on the history of the current branch "just
work" in that state. They update the HEAD to point at the new
history without affecting any branch when the HEAD is detached, just
like they update the tip of the "current branch" to point at the new
history when HEAD points at a specific branch.
As this is done as the natural extension for these commands, we did
not, we still do not, and we do not want to repeat "A detached HEAD
is updated without affecting any branch" when describing what each
and every one of these commands that operates "on the current branch"
does.
Add a blanket description to the glossary to cover them instead.
The general principle is that operations to update the branch work
on and affect the HEAD, while operations to update the information
about a branch do not.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Philip Oakley
Junio C Hamano
Reuven Y
Sergey Organov
Mark Rushakoff
Thomas Gummerer
Nguyễn Thái Ngọc Duy
Ville Skyttä
Manav Rathi
Liam Beguin
Brandon Williams
Linus Torvalds
René Nyffenegger
Stephen P. Smith
David Turner
Stefan Beller
Thomas Ackermann
Jeremiah Mahler
Jeff King
Richard Hansen
Michael Schubert
Jonathan Nieder
Johan Herland