glossary: improve definitions of refspec and pathspec
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>
Thomas Ackermann committed
Apr 15, 2013 at 19:50 UTC
57148ebb30fd7ed72acf7b3fc6f59d7cf2d94643
1 file changed
+10
-23
Documentation/glossary-content.txt
+10
-23
@@ -268,7 +268,7 @@ This commit is referred to as a "merge commit", or sometimes just a
268
pack.
269
270
[[def_pathspec]]pathspec::
271
- Pattern used to specify paths.
271
+ Pattern used to limit paths in Git commands.
272
+
273
Pathspecs are used on the command line of "git ls-files", "git
274
ls-tree", "git add", "git grep", "git diff", "git checkout",
@@ -277,6 +277,8 @@ limit the scope of operations to some subset of the tree or
277
worktree. See the documentation of each command for whether
278
paths are relative to the current directory or toplevel. The
279
pathspec syntax is as follows:
280
++
281
+--
282
283
* any path matches itself
284
* the pathspec up to the last slash represents a
@@ -286,11 +288,12 @@ pathspec syntax is as follows:
288
of the pathname. Paths relative to the directory
289
prefix will be matched against that pattern using fnmatch(3);
290
in particular, '*' and '?' _can_ match directory separators.
291
+
292
+--
293
+
294
For example, Documentation/*.jpg will match all .jpg files
295
in the Documentation subtree,
296
including Documentation/chapter_1/figure_1.jpg.
293
-
297
+
298
A pathspec that begins with a colon `:` has special meaning. In the
299
short form, the leading colon `:` is followed by zero or more "magic
@@ -306,18 +309,10 @@ and a close parentheses `)`, and the remainder is the pattern to match
309
against the path.
310
+
311
The "magic signature" consists of an ASCII symbol that is not
309
-alphanumeric.
310
-+
311
---
312
-top `/`;;
313
- The magic word `top` (mnemonic: `/`) makes the pattern match
314
- from the root of the working tree, even when you are running
315
- the command from inside a subdirectory.
316
---
317
-+
318
-Currently only the slash `/` is recognized as the "magic signature",
319
-but it is envisioned that we will support more types of magic in later
320
-versions of Git.
312
+alphanumeric. Currently only the slash `/` is recognized as a
313
+"magic signature": it makes the pattern match from the root of
314
+the working tree, even when you are running the command from
315
+inside a subdirectory.
316
+
317
A pathspec with only a colon means "there is no pathspec". This form
318
should not be combined with other pathspec.
@@ -389,15 +384,7 @@ should not be combined with other pathspec.
384
[[def_refspec]]refspec::
385
A "refspec" is used by <<def_fetch,fetch>> and
386
<<def_push,push>> to describe the mapping between remote
392
- <<def_ref,ref>> and local ref. They are combined with a colon in
393
- the format <src>:<dst>, preceded by an optional plus sign, +.
394
- For example: `git fetch $URL
395
- refs/heads/master:refs/heads/origin` means "grab the master
396
- <<def_branch,branch>> <<def_head,head>> from the $URL and store
397
- it as my origin branch head". And `git push
398
- $URL refs/heads/master:refs/heads/to-upstream` means "publish my
399
- master branch head as to-upstream branch at $URL". See also
400
- linkgit:git-push[1].
387
+ <<def_ref,ref>> and local ref.
388
389
[[def_remote_tracking_branch]]remote-tracking branch::
390
A regular Git <<def_branch,branch>> that is used to follow changes from