From: Junio C Hamano Date: Mon, 1 Aug 2011 21:44:24 +0000 (-0700) Subject: Merge branch 'nk/ref-doc' into maint X-Git-Tag: v1.7.6.1~41 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/3503b8d0da61d920ebd9294fd6a9a0f758328fd3?hp=-c Merge branch 'nk/ref-doc' into maint * nk/ref-doc: glossary: clarify description of HEAD glossary: update description of head and ref glossary: update description of "tag" git.txt: de-emphasize the implementation detail of a ref check-ref-format doc: de-emphasize the implementation detail of a ref git-remote.txt: avoid sounding as if loose refs are the only ones in the world git-remote.txt: fix wrong remote refspec --- 3503b8d0da61d920ebd9294fd6a9a0f758328fd3 diff --combined Documentation/git.txt index 3c7a832343,7fc6b88b96..0172cd7014 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@@ -9,7 -9,7 +9,7 @@@ git - the stupid content tracke SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=]] [--html-path] +'git' [--version] [--exec-path[=]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=] [--work-tree=] [-c =] @@@ -44,11 -44,6 +44,11 @@@ unreleased) version of git, that is ava branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.7.6/git.html[documentation for release 1.7.6] + +* release notes for + link:RelNotes/1.7.6.txt[1.7.6]. + * link:v1.7.5.4/git.html[documentation for release 1.7.5.4] * release notes for @@@ -296,16 -291,8 +296,16 @@@ help ...` the current setting and then exit. --html-path:: - Print the path to wherever your git HTML documentation is installed - and exit. + Print the path, without trailing slash, where git's HTML + documentation is installed and exit. + +--man-path:: + Print the manpath (see `man(1)`) for the man pages for + this version of git and exit. + +--info-path:: + Print the path where the Info files documenting this + version of git are installed and exit. -p:: --paginate:: @@@ -523,16 -510,15 +523,15 @@@ Any git command accepting any symbolic notation: HEAD:: - indicates the head of the current branch (i.e. the - contents of `$GIT_DIR/HEAD`). + indicates the head of the current branch. :: a valid tag 'name' - (i.e. the contents of `$GIT_DIR/refs/tags/`). + (i.e. a `refs/tags/` reference). :: a valid head 'name' - (i.e. the contents of `$GIT_DIR/refs/heads/`). + (i.e. a `refs/heads/` reference). For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. diff --combined Documentation/glossary-content.txt index 8f62d1abee,f4fd5b046d..3595b586bc --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@@ -161,8 -161,8 +161,8 @@@ to point at the new commit [[def_head]]head:: A <> to the <> at the tip of a - <>. Heads are stored in - `$GIT_DIR/refs/heads/`, except when using packed refs. (See + <>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See linkgit:git-pack-refs[1].) [[def_HEAD]]HEAD:: @@@ -170,8 -170,8 +170,8 @@@ working tree>> is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the <> in your repository, except when using a - <>, in which case it may - reference an arbitrary commit. + <>, in which case it directly + references an arbitrary commit. [[def_head_ref]]head ref:: A synonym for <>. @@@ -277,8 -277,7 +277,8 @@@ This commit is referred to as a "merge Pattern used to specify paths. + Pathspecs are used on the command line of "git ls-files", "git -ls-tree", "git grep", "git checkout", and many other commands to +ls-tree", "git add", "git grep", "git diff", "git checkout", +and many other commands to limit the scope of operations to some subset of the tree or worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The @@@ -297,37 -296,6 +297,37 @@@ For example, Documentation/*.jpg will m in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. ++ +A pathspec that begins with a colon `:` has special meaning. In the +short form, the leading colon `:` is followed by zero or more "magic +signature" letters (which optionally is terminated by another colon `:`), +and the remainder is the pattern to match against the path. The optional +colon that terminates the "magic signature" can be omitted if the pattern +begins with a character that cannot be a "magic signature" and is not a +colon. ++ +In the long form, the leading colon `:` is followed by a open +parenthesis `(`, a comma-separated list of zero or more "magic words", +and a close parentheses `)`, and the remainder is the pattern to match +against the path. ++ +The "magic signature" consists of an ASCII symbol that is not +alphanumeric. ++ +-- +top `/`;; + The magic word `top` (mnemonic: `/`) makes the pattern match + from the root of the working tree, even when you are running + the command from inside a subdirectory. +-- ++ +Currently only the slash `/` is recognized as the "magic signature", +but it is envisioned that we will support more types of magic in later +versions of git. ++ +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. + [[def_parent]]parent:: A <> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its @@@ -382,8 -350,9 +382,9 @@@ [[def_ref]]ref:: A 40-byte hex representation of a <> or a name that - denotes a particular <>. These may be stored in - `$GIT_DIR/refs/`. + denotes a particular <>. They may be stored in + a file under `$GIT_DIR/refs/` directory, or + in the `$GIT_DIR/packed-refs` file. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, @@@ -459,14 -428,14 +460,14 @@@ command. [[def_tag]]tag:: - A <> pointing to a <> or - <>. In contrast to a <>, - a tag is not changed by a <>. Tags (not - <>) are stored in `$GIT_DIR/refs/tags/`. A - git tag has nothing to do with a Lisp tag (which would be - called an <> in git's context). A - tag is most typically used to mark a particular point in the - commit ancestry <>. + A <> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <> or a <>). + In contrast to a <>, a tag is not updated by + the `commit` command. A git tag has nothing to do with a Lisp + tag (which would be called an <> + in git's context). A tag is most typically used to mark a particular + point in the commit ancestry <>. [[def_tag_object]]tag object:: An <> containing a <> pointing to