diff options
Diffstat (limited to 'Documentation')
32 files changed, 423 insertions, 230 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt index b27b0d5c06..d1a4bec0d4 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -64,9 +64,11 @@ core.ignoreStat:: slow, such as Microsoft Windows. See gitlink:git-update-index[1]. False by default. -core.onlyUseSymrefs:: - Always use the "symref" format instead of symbolic links for HEAD - and other symbolic reference files. True by default. +core.preferSymlinkRefs:: + Instead of the default "symref" format for HEAD + and other symbolic reference files, use symbolic links. + This is sometimes needed to work with old scripts that + expect HEAD to be a symbolic link. core.repositoryFormatVersion:: Internal variable identifying the repository format and layout diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 4211c81972..d1360ecde2 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -971,7 +971,7 @@ $ git show-branch --topo-order master mybranch The first two lines indicate that it is showing the two branches and the first line of the commit log message from their top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `*` character), and the first column for +(notice the asterisk `\*` character), and the first column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index ae24547c8a..5e3112943d 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -26,7 +26,7 @@ OPTIONS -v:: Be verbose. ---:: +\--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 09bd6a5535..765c173e15 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -63,7 +63,7 @@ OPTIONS Only meaningful with `--stdin`; paths are separated with NUL character instead of LF. ---:: +\--:: Do not interpret any more arguments as options. The order of the flags used to matter, but not anymore. diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 9a5e37186f..893baaa6f6 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -11,11 +11,20 @@ SYNOPSIS DESCRIPTION ----------- -Each commit between the fork-point and <head> is examined, and compared against -the change each commit between the fork-point and <upstream> introduces. -Commits already included in upstream are prefixed with '-' (meaning "drop from -my local pull"), while commits missing from upstream are prefixed with '+' -(meaning "add to the updated upstream"). +The changeset (or "diff") of each commit between the fork-point and <head> +is compared against each commit between the fork-point and <upstream>. + +Every commit with a changeset that doesn't exist in the other branch +has its id (sha1) reported, prefixed by a symbol. Those existing only +in the <upstream> branch are prefixed with a minus (-) sign, and those +that only exist in the <head> branch are prefixed with a plus (+) symbol. + +Because git-cherry compares the changeset rather than the commit id +(sha1), you can use git-cherry to find out if a commit you made locally +has been applied <upstream> under a different commit id. For example, +this will happen if you're feeding patches <upstream> via email rather +than pushing or pulling commits directly. + OPTIONS ------- diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 36890c543d..c61afbcdba 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git-clean' [-d] [-n] [-q] [-x | -X] +'git-clean' [-d] [-n] [-q] [-x | -X] [--] <paths>... DESCRIPTION ----------- @@ -16,6 +16,9 @@ Removes files unknown to git. This allows to clean the working tree from files that are not under version control. If the '-x' option is specified, ignored files are also removed, allowing to remove all build products. +When optional `<paths>...` arguments are given, the paths +affected are further limited to those that match them. + OPTIONS ------- diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 131e445747..b333f51045 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -101,7 +101,7 @@ OPTIONS is not allowed. Examples -~~~~~~~~ +-------- Clone from upstream:: + diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0a7365b9a8..38df59ce23 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -106,7 +106,7 @@ but can be used to amend a merge commit. index and the latest commit does not match on the specified paths to avoid confusion. ---:: +\--:: Do not interpret any more arguments as options. <file>...:: diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 47216f488b..198ce77a8a 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -7,13 +7,23 @@ git-count-objects - Reports on unpacked objects SYNOPSIS -------- -'git-count-objects' +'git-count-objects' [-v] DESCRIPTION ----------- This counts the number of unpacked object files and disk space consumed by them, to help you decide when it is a good time to repack. + +OPTIONS +------- +-v:: + In addition to the number of loose objects and disk + space consumed, it reports the number of in-pack + objects, and number of objects that can be removed by + running `git-prune-packed`. + + Author ------ Written by Junio C Hamano <junkio@cox.net> diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index d30435a9e4..56bd3e517d 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,7 @@ git-cvsexportcommit - Export a commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [PARENTCOMMIT] COMMITID +'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -39,6 +39,13 @@ OPTIONS Be pedantic (paranoid) when applying patches. Invokes patch with --fuzz=0 +-f:: + Force the merge even if the files are not up to date. + +-m:: + Prepend the commit message with the provided prefix. + Useful for patch series and the like. + -v:: Verbose. diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 2169169850..906830d4bf 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -92,7 +92,7 @@ separated with a single space are given. Furthermore, it lists only files which were modified from all parents. --cc:: +--cc:: This flag changes the way a merge commit patch is displayed, in a similar way to the '-c' option. It implies the '-c' and '-p' options and further compresses the patch output diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index cfc0d88d02..eca9e9ccef 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -29,6 +29,7 @@ CONFIGURATION git-imap-send requires the following values in the repository configuration file (shown with examples): +.......................... [imap] Folder = "INBOX.Drafts" @@ -38,8 +39,9 @@ configuration file (shown with examples): [imap] Host = imap.server.com User = bob - Password = pwd + Pass = pwd Port = 143 +.......................... BUGS diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index af378ffcf9..c9ffff734c 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -51,7 +51,7 @@ git log v2.6.12.. include/scsi drivers/scsi:: Show all commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git log --since="2 weeks ago" -- gitk:: +git log --since="2 weeks ago" \-- gitk:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 796d049be6..a29c633c8d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -106,7 +106,7 @@ OPTIONS lines, show only handful hexdigits prefix. Non default number of digits can be specified with --abbrev=<n>. ---:: +\--:: Do not interpret any more arguments as options. <file>:: diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index fbc986aa84..332e023d0f 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Runs a merge for files needing merging SYNOPSIS -------- -'git-merge-index' [-o] [-q] <merge-program> (-a | -- | <file>\*) +'git-merge-index' [-o] [-q] <merge-program> (-a | \-- | <file>\*) DESCRIPTION ----------- @@ -19,7 +19,7 @@ files are passed as arguments 5, 6 and 7. OPTIONS ------- ---:: +\--:: Do not interpret any more arguments as options. -a:: diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 68707083be..ffaa00468f 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -41,6 +41,7 @@ Enter git-name-rev: ------------ % git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a +33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99^0~940 ------------ Now you are wiser, because you know that it happened 940 revisions before v0.99. diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index f694fcbde8..a11e303094 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -28,7 +28,7 @@ OPTIONS Do not remove anything; just report what it would remove. ---:: +\--:: Do not interpret any more arguments as options. <head>...:: diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 844cfda8d2..1f21d95684 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--aggressive]| --reset] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -63,6 +63,15 @@ OPTIONS * when both sides adds a path identically. The resolution is to add that path. +--prefix=<prefix>/:: + Keep the current index contents, and read the contents + of named tree-ish under directory at `<prefix>`. The + original index file cannot have anything at the path + `<prefix>` itself, and have nothing in `<prefix>/` + directory. Note that the `<prefix>/` value must end + with a slash. + + <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 4a7e67a4d2..1b482abecd 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -3,38 +3,54 @@ git-rebase(1) NAME ---- -git-rebase - Rebase local commits to new upstream head +git-rebase - Rebase local commits to a new head SYNOPSIS -------- 'git-rebase' [--onto <newbase>] <upstream> [<branch>] +'git-rebase' --continue + +'git-rebase' --abort + DESCRIPTION ----------- -git-rebase applies to <upstream> (or optionally to <newbase>) commits -from <branch> that do not appear in <upstream>. When <branch> is not -specified it defaults to the current branch (HEAD). +git-rebase replaces <branch> with a new branch of the same name. When +the --onto option is provided the new branch starts out with a HEAD equal +to <newbase>, otherwise it is equal to <upstream>. It then attempts to +create a new commit for each commit from the original <branch> that does +not exist in the <upstream> branch. -When git-rebase is complete, <branch> will be updated to point to the -newly created line of commit objects, so the previous line will not be -accessible unless there are other references to it already. +It is possible that a merge failure will prevent this process from being +completely automatic. You will have to resolve any such merge failure +and run `git rebase --continue`. If you can not resolve the merge +failure, running `git rebase --abort` will restore the original <branch> +and remove the working files found in the .dotest directory. + +Note that if <branch> is not specified on the command line, the currently +checked out branch is used. Assume the following history exists and the current branch is "topic": +------------ A---B---C topic / D---E---F---G master +------------ From this point, the result of either of the following commands: + git-rebase master git-rebase master topic would be: +------------ A'--B'--C' topic / D---E---F---G master +------------ While, starting from the same point, the result of either of the following commands: @@ -44,21 +60,33 @@ commands: would be: +------------ A'--B'--C' topic / D---E---F---G master +------------ In case of conflict, git-rebase will stop at the first problematic commit -and leave conflict markers in the tree. After resolving the conflict manually -and updating the index with the desired resolution, you can continue the -rebasing process with +and leave conflict markers in the tree. You can use git diff to locate +the markers (<<<<<<) and make edits to resolve the conflict. For each +file you edit, you need to tell git that the conflict has been resolved, +typically this would be done with + + + git update-index <filename> + + +After resolving the conflict manually and updating the index with the +desired resolution, you can continue the rebasing process with + + + git rebase --continue - git am --resolved --3way Alternatively, you can undo the git-rebase with - git reset --hard ORIG_HEAD - rm -r .dotest + + git rebase --abort OPTIONS ------- @@ -73,6 +101,28 @@ OPTIONS <branch>:: Working branch; defaults to HEAD. +--continue:: + Restart the rebasing process after having resolved a merge conflict. + +--abort:: + Restore the original branch and abort the rebase operation. + +NOTES +----- +When you rebase a branch, you are changing its history in a way that +will cause problems for anyone who already has a copy of the branch +in their repository and tries to pull updates from you. You should +understand the implications of using 'git rebase' on a repository that +you share. + +When the git rebase command is run, it will first execute a "pre-rebase" +hook if one exists. You can use this hook to do sanity checks and +reject the rebase if it isn't appropriate. Please see the template +pre-rebase hook script for an example. + +You must be in the top directory of your project to start (or continue) +a rebase. Upon completion, <branch> will be the current branch. + Author ------ Written by Junio C Hamano <junkio@cox.net> diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index d2f9a44382..951622774a 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -38,6 +38,7 @@ OPTIONS -d:: After packing, if the newly created packs make some existing packs redundant, remove the redundant packs. + Also runs gitlink:git-prune-packed[1]. -l:: Pass the `--local` option to `git pack-objects`, see diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 566cfa1836..660c18ff8d 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -23,10 +23,11 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -If you want to set/unset an option which can occur on multiple lines, you -should provide a POSIX regex for the value. If you want to handle the lines -*not* matching the regex, just prepend a single exclamation mark in front -(see EXAMPLES). +If you want to set/unset an option which can occur on multiple +lines, a POSIX regexp `value_regex` needs to be given. Only the +existing values that match the regexp are updated or unset. If +you want to handle the lines that do *not* match the regex, just +prepend a single exclamation mark in front (see EXAMPLES). The type specifier can be either '--int' or '--bool', which will make 'git-repo-config' ensure that the variable(s) are of the given type and @@ -34,10 +35,10 @@ convert the value to the canonical form (simple decimal number for int, a "true" or "false" string for bool). If no type specifier is passed, no checks or transformations are performed on the value. -This command will fail if +This command will fail if: -. .git/config is invalid, -. .git/config can not be written to, +. The .git/config file is invalid, +. Can not write to .git/config, . no section was provided, . the section or key is invalid, . you try to unset an option which does not exist, or @@ -49,7 +50,7 @@ OPTIONS --replace-all:: Default behaviour is to replace at most one line. This replaces - all lines matching the key (and optionally the value_regex) + all lines matching the key (and optionally the value_regex). --get:: Get the value for a given key (optionally filtered by a regex @@ -59,6 +60,9 @@ OPTIONS Like get, but does not fail if the number of values for the key is not exactly one. +--get-regexp:: + Like --get-all, but interprets the name as a regular expression. + --unset:: Remove the line matching the key from .git/config. diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index ebcfe5edb7..b27399dd41 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -43,7 +43,7 @@ OPTIONS Commit to make the current HEAD. Examples -~~~~~~~~ +-------- Undo a commit and redo:: + diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 8255ae1bce..ad6d14c55a 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -68,9 +68,10 @@ OPTIONS --bisect:: Limit output to the one commit object which is roughly halfway between the included and excluded commits. Thus, if 'git-rev-list - --bisect foo ^bar ^baz' outputs 'midpoint', the output - of 'git-rev-list foo ^midpoint' and 'git-rev-list midpoint - ^bar ^baz' would be of roughly the same length. Finding the change + --bisect foo {caret}bar {caret}baz' outputs 'midpoint', the output + of 'git-rev-list foo {caret}midpoint' and 'git-rev-list midpoint + {caret}bar {caret}baz' would be of roughly the same length. + Finding the change which introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length one. diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index c9c3088424..66fc478f57 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -32,7 +32,7 @@ OPTIONS -v:: Be verbose. ---:: +\--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options). diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 18280628a1..c20b38b08a 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -13,9 +13,16 @@ SYNOPSIS DESCRIPTION ----------- -Reads a packed archive (.pack) from the standard input, and -expands the objects contained in the pack into "one-file -one-object" format in $GIT_OBJECT_DIRECTORY. +Read a packed archive (.pack) from the standard input, expanding +the objects contained within and writing them into the repository in +"loose" (one object per file) format. + +Objects that already exist in the repository will *not* be unpacked +from the pack-file. Therefore, nothing will be unpacked if you use +this command on a pack-file that exists within the target repository. + +Please see the `git-repack` documentation for options to generate +new packs and replace existing ones. OPTIONS ------- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index d4137fc87e..d043e86a77 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -10,12 +10,12 @@ SYNOPSIS -------- [verse] 'git-update-index' - [--add] [--remove | --force-remove] [--replace] - [--refresh [-q] [--unmerged] [--ignore-missing]] + [--add] [--remove | --force-remove] [--replace] + [--refresh] [-q] [--unmerged] [--ignore-missing] [--cacheinfo <mode> <object> <file>]\* [--chmod=(+|-)x] [--assume-unchanged | --no-assume-unchanged] - [--really-refresh] + [--really-refresh] [--unresolve] [--again] [--info-only] [--index-info] [-z] [--stdin] [--verbose] @@ -80,6 +80,14 @@ OPTIONS filesystem that has very slow lstat(2) system call (e.g. cifs). +--again:: + Runs `git-update-index` itself on the paths whose index + entries are different from those from the `HEAD` commit. + +--unresolve:: + Restores the 'unmerged' or 'needs updating' state of a + file during a merge if it was cleared by accident. + --info-only:: Do not create objects in the object database for all <file> arguments that follow this flag; just insert @@ -109,7 +117,7 @@ OPTIONS Only meaningful with `--stdin`; paths are separated with NUL character instead of LF. ---:: +\--:: Do not interpret any more arguments as options. <file>:: diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 4962d6975f..7a6132b016 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -25,7 +25,7 @@ OPTIONS -v:: After verifying the pack, show list of objects contained in the pack. ---:: +\--:: Do not interpret any more arguments as options. OUTPUT FORMAT diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index 641cb7ea97..e8f21d02f7 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -58,7 +58,7 @@ git-whatchanged -p v2.6.12.. include/scsi drivers/scsi:: Show as patches the commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -git-whatchanged --since="2 weeks ago" -- gitk:: +git-whatchanged --since="2 weeks ago" \-- gitk:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index 77e12cb949..c85fa89c30 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -8,7 +8,7 @@ git-write-tree - Creates a tree object from the current index SYNOPSIS -------- -'git-write-tree' [--missing-ok] +'git-write-tree' [--missing-ok] [--prefix=<prefix>/] DESCRIPTION ----------- @@ -30,6 +30,12 @@ OPTIONS directory exist in the object database. This option disables this check. +--prefix=<prefix>/:: + Writes a tree object that represents a subdirectory + `<prefix>`. This can be used to write the tree object + for a subproject that is in the named subdirectory. + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index eb126d7a4b..cb482bf98e 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -31,7 +31,7 @@ gitk v2.6.12.. include/scsi drivers/scsi:: Show as the changes since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories -gitk --since="2 weeks ago" -- gitk:: +gitk --since="2 weeks ago" \-- gitk:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 02a9d9c18a..39c90ad7a6 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -1,79 +1,57 @@ -object:: - The unit of storage in git. It is uniquely identified by - the SHA1 of its contents. Consequently, an object can not - be changed. - -object name:: - The unique identifier of an object. The hash of the object's contents - using the Secure Hash Algorithm 1 and usually represented by the 40 - character hexadecimal encoding of the hash of the object (possibly - followed by a white space). - -SHA1:: - Synonym for object name. - -object identifier:: - Synonym for object name. - -hash:: - In git's context, synonym to object name. +alternate object database:: + Via the alternates mechanism, a repository can inherit part of its + object database from another object database, which is called + "alternate". -object database:: - Stores a set of "objects", and an individual object is identified - by its object name. The objects usually live in `$GIT_DIR/objects/`. +bare repository:: + A bare repository is normally an appropriately named + directory with a `.git` suffix that does not have a + locally checked-out copy of any of the files under revision + control. That is, all of the `git` administrative and + control files that would normally be present in the + hidden `.git` sub-directory are directly present in + the `repository.git` directory instead, and no other files + are present and checked out. Usually publishers of public + repositories make bare repositories available. blob object:: Untyped object, e.g. the contents of a file. -tree object:: - An object containing a list of file names and modes along with refs - to the associated blob and/or tree objects. A tree is equivalent - to a directory. - -tree:: - Either a working tree, or a tree object together with the - dependent blob and tree objects (i.e. a stored representation - of a working tree). - -DAG:: - Directed acyclic graph. The commit objects form a directed acyclic - graph, because they have parents (directed), and the graph of commit - objects is acyclic (there is no chain which begins and ends with the - same object). - -index:: - A collection of files with stat information, whose contents are - stored as objects. The index is a stored version of your working - tree. Truth be told, it can also contain a second, and even a third - version of a working tree, which are used when merging. - -index entry:: - The information regarding a particular file, stored in the index. - An index entry can be unmerged, if a merge was started, but not - yet finished (i.e. if the index contains multiple versions of - that file). - -unmerged index: - An index which contains unmerged index entries. +branch:: + A non-cyclical graph of revisions, i.e. the complete history of + a particular revision, which is called the branch head. The + branch heads are stored in `$GIT_DIR/refs/heads/`. cache:: Obsolete for: index. -working tree:: - The set of files and directories currently being worked on, - i.e. you can work in your working tree without using git at all. - -directory:: - The list you get with "ls" :-) +chain:: + A list of objects, where each object in the list contains a + reference to its successor (for example, the successor of a commit + could be one of its parents). -revision:: - A particular state of files and directories which was stored in - the object database. It is referenced by a commit object. +changeset:: + BitKeeper/cvsps speak for "commit". Since git does not store + changes, but states, it really does not make sense to use + the term "changesets" with git. checkout:: The action of updating the working tree to a revision which was stored in the object database. +cherry-picking:: + In SCM jargon, "cherry pick" means to choose a subset of + changes out of a series of changes (typically commits) + and record them as a new series of changes on top of + different codebase. In GIT, this is performed by + "git cherry-pick" command to extract the change + introduced by an existing commit and to record it based + on the tip of the current branch as a new commit. + +clean:: + A working tree is clean, if it corresponds to the revision + referenced by the current head. Also see "dirty". + commit:: As a verb: The action of storing the current state of the index in the object database. The result is a revision. @@ -85,73 +63,90 @@ commit object:: tree object which corresponds to the top directory of the stored revision. -parent:: - A commit object contains a (possibly empty) list of the logical - predecessor(s) in the line of development, i.e. its parents. +core git:: + Fundamental data structures and utilities of git. Exposes only + limited source code management tools. -changeset:: - BitKeeper/cvsps speak for "commit". Since git does not store - changes, but states, it really does not make sense to use - the term "changesets" with git. +DAG:: + Directed acyclic graph. The commit objects form a directed acyclic + graph, because they have parents (directed), and the graph of commit + objects is acyclic (there is no chain which begins and ends with the + same object). -clean:: - A working tree is clean, if it corresponds to the revision - referenced by the current head. +dircache:: + You are *waaaaay* behind. dirty:: A working tree is said to be dirty if it contains modifications which have not been committed to the current branch. -head:: - The top of a branch. It contains a ref to the corresponding - commit object. +directory:: + The list you get with "ls" :-) -branch:: - A non-cyclical graph of revisions, i.e. the complete history of - a particular revision, which is called the branch head. The - branch heads are stored in `$GIT_DIR/refs/heads/`. +ent:: + Favorite synonym to "tree-ish" by some total geeks. See + `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth + explanation. -master:: - The default branch. Whenever you create a git repository, a branch - named "master" is created, and becomes the active branch. In most - cases, this contains the local development. +fast forward:: + A fast-forward is a special type of merge where you have + a revision and you are "merging" another branch's changes + that happen to be a descendant of what you have. + In such these cases, you do not make a new merge commit but + instead just update to his revision. This will happen + frequently on a tracking branch of a remote repository. -origin:: - The default upstream branch. Most projects have one upstream - project which they track, and by default 'origin' is used for - that purpose. New updates from upstream will be fetched into - this branch; you should never commit to it yourself. +fetch:: + Fetching a branch means to get the branch's head ref from a + remote repository, to find out which objects are missing from + the local object database, and to get them, too. -ref:: - A 40-byte hex representation of a SHA1 pointing to a particular - object. These may be stored in `$GIT_DIR/refs/`. +file system:: + Linus Torvalds originally designed git to be a user space file + system, i.e. the infrastructure to hold files and directories. + That ensured the efficiency and speed of git. + +git archive:: + Synonym for repository (for arch people). + +hash:: + In git's context, synonym to object name. + +head:: + The top of a branch. It contains a ref to the corresponding + commit object. head ref:: A ref pointing to a head. Often, this is abbreviated to "head". Head refs are stored in `$GIT_DIR/refs/heads/`. -tree-ish:: - A ref pointing to either a commit object, a tree object, or a - tag object pointing to a tag or commit or tree object. +hook:: + During the normal execution of several git commands, + call-outs are made to optional scripts that allow + a developer to add functionality or checking. + Typically, the hooks allow for a command to be pre-verified + and potentially aborted, and allow for a post-notification + after the operation is done. + The hook scripts are found in the `$GIT_DIR/hooks/` directory, + and are enabled by simply making them executable. -ent:: - Favorite synonym to "tree-ish" by some total geeks. See - `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth - explanation. +index:: + A collection of files with stat information, whose contents are + stored as objects. The index is a stored version of your working + tree. Truth be told, it can also contain a second, and even a third + version of a working tree, which are used when merging. -tag object:: - An object containing a ref pointing to another object, which can - contain a message just like a commit object. It can also - contain a (PGP) signature, in which case it is called a "signed - tag object". +index entry:: + The information regarding a particular file, stored in the index. + An index entry can be unmerged, if a merge was started, but not + yet finished (i.e. if the index contains multiple versions of + that file). -tag:: - A ref pointing to a tag or commit object. In contrast to a head, - a tag is not changed by a commit. Tags (not tag objects) are - stored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with - a Lisp tag (which is called object type in git's context). - A tag is most typically used to mark a particular point in the - commit ancestry chain. +master:: + The default development branch. Whenever you create a git + repository, a branch named "master" is created, and becomes + the active branch. In most cases, this contains the local + development, though that is purely conventional and not required. merge:: To merge branches means to try to accumulate the changes since a @@ -159,55 +154,65 @@ merge:: merge uses heuristics to accomplish that. Evidently, an automatic merge can fail. -octopus:: - To merge more than two branches. Also denotes an intelligent - predator. +object:: + The unit of storage in git. It is uniquely identified by + the SHA1 of its contents. Consequently, an object can not + be changed. -resolve:: - The action of fixing up manually what a failed automatic merge - left behind. +object database:: + Stores a set of "objects", and an individual object is identified + by its object name. The objects usually live in `$GIT_DIR/objects/`. -rewind:: - To throw away part of the development, i.e. to assign the head to - an earlier revision. +object identifier:: + Synonym for object name. -rebase:: - To clean a branch by starting from the head of the main line of - development ("master"), and reapply the (possibly cherry-picked) - changes from that branch. +object name:: + The unique identifier of an object. The hash of the object's contents + using the Secure Hash Algorithm 1 and usually represented by the 40 + character hexadecimal encoding of the hash of the object (possibly + followed by a white space). -repository:: - A collection of refs together with an object database containing - all objects, which are reachable from the refs, possibly accompanied - by meta data from one or more porcelains. A repository can - share an object database with other repositories. +object type: + One of the identifiers "commit","tree","tag" and "blob" describing + the type of an object. -git archive:: - Synonym for repository (for arch people). +octopus:: + To merge more than two branches. Also denotes an intelligent + predator. -file system:: - Linus Torvalds originally designed git to be a user space file - system, i.e. the infrastructure to hold files and directories. - That ensured the efficiency and speed of git. +origin:: + The default upstream tracking branch. Most projects have at + least one upstream project which they track. By default + 'origin' is used for that purpose. New upstream updates + will be fetched into this branch; you should never commit + to it yourself. -alternate object database:: - Via the alternates mechanism, a repository can inherit part of its - object database from another object database, which is called - "alternate". +pack:: + A set of objects which have been compressed into one file (to save + space or to transmit them efficiently). -reachable:: - An object is reachable from a ref/commit/tree/tag, if there is a - chain leading from the latter to the former. +pack index:: + The list of identifiers, and other information, of the objects in a + pack, to assist in efficiently accessing the contents of a pack. -chain:: - A list of objects, where each object in the list contains a - reference to its successor (for example, the successor of a commit - could be one of its parents). +parent:: + A commit object contains a (possibly empty) list of the logical + predecessor(s) in the line of development, i.e. its parents. -fetch:: - Fetching a branch means to get the branch's head ref from a - remote repository, to find out which objects are missing from - the local object database, and to get them, too. +pickaxe:: + The term pickaxe refers to an option to the diffcore routines + that help select changes that add or delete a given text string. + With the --pickaxe-all option, it can be used to view the + full changeset that introduced or removed, say, a particular + line of text. See gitlink:git-diff[1]. + +plumbing:: + Cute name for core git. + +porcelain:: + Cute name for programs and program suites depending on core git, + presenting a high level access to core git. Porcelains expose + more of a SCM interface than the plumbing. pull:: Pulling a branch means to fetch it and merge it. @@ -221,33 +226,101 @@ push:: the remote head ref. If the remote head is not an ancestor to the local head, the push fails. -pack:: - A set of objects which have been compressed into one file (to save - space or to transmit them efficiently). +reachable:: + An object is reachable from a ref/commit/tree/tag, if there is a + chain leading from the latter to the former. -pack index:: - The list of identifiers, and other information, of the objects in a - pack, to assist in efficiently accessing the contents of a pack. +rebase:: + To clean a branch by starting from the head of the main line of + development ("master"), and reapply the (possibly cherry-picked) + changes from that branch. -core git:: - Fundamental data structures and utilities of git. Exposes only - limited source code management tools. +ref:: + A 40-byte hex representation of a SHA1 or a name that denotes + a particular object. These may be stored in `$GIT_DIR/refs/`. + +refspec:: + A refspec is used by fetch and push to describe the mapping + between remote ref and local ref. They are combined with + a colon in the format <src>:<dst>, preceded by an optional + plus sign, +. For example: + `git fetch $URL refs/heads/master:refs/heads/origin` + means "grab the master branch head from the $URL and store + it as my origin branch head". + And `git push $URL refs/heads/master:refs/heads/to-upstream` + means "publish my master branch head as to-upstream master head + at $URL". See also gitlink:git-push[1] -plumbing:: - Cute name for core git. +repository:: + A collection of refs together with an object database containing + all objects, which are reachable from the refs, possibly accompanied + by meta data from one or more porcelains. A repository can + share an object database with other repositories. -porcelain:: - Cute name for programs and program suites depending on core git, - presenting a high level access to core git. Porcelains expose - more of a SCM interface than the plumbing. +resolve:: + The action of fixing up manually what a failed automatic merge + left behind. -object type: - One of the identifiers "commit","tree","tag" and "blob" describing - the type of an object. +revision:: + A particular state of files and directories which was stored in + the object database. It is referenced by a commit object. + +rewind:: + To throw away part of the development, i.e. to assign the head to + an earlier revision. SCM:: Source code management (tool). -dircache:: - You are *waaaaay* behind. +SHA1:: + Synonym for object name. + +topic branch:: + A regular git branch that is used by a developer to + identify a conceptual line of development. Since branches + are very easy and inexpensive, it is often desirable to + have several small branches that each contain very well + defined concepts or small incremental yet related changes. + +tracking branch:: + A regular git branch that is used to follow changes from + another repository. A tracking branch should not contain + direct modifications or have local commits made to it. + A tracking branch can usually be identified as the + right-hand-side ref in a Pull: refspec. + +tree object:: + An object containing a list of file names and modes along with refs + to the associated blob and/or tree objects. A tree is equivalent + to a directory. + +tree:: + Either a working tree, or a tree object together with the + dependent blob and tree objects (i.e. a stored representation + of a working tree). + +tree-ish:: + A ref pointing to either a commit object, a tree object, or a + tag object pointing to a tag or commit or tree object. + +tag object:: + An object containing a ref pointing to another object, which can + contain a message just like a commit object. It can also + contain a (PGP) signature, in which case it is called a "signed + tag object". + +tag:: + A ref pointing to a tag or commit object. In contrast to a head, + a tag is not changed by a commit. Tags (not tag objects) are + stored in `$GIT_DIR/refs/tags/`. A git tag has nothing to do with + a Lisp tag (which is called object type in git's context). + A tag is most typically used to mark a particular point in the + commit ancestry chain. + +unmerged index: + An index which contains unmerged index entries. + +working tree:: + The set of files and directories currently being worked on, + i.e. you can work in your working tree without using git at all. diff --git a/Documentation/sort_glossary.pl b/Documentation/sort_glossary.pl index e57dc78e0e..e0bc552a64 100644 --- a/Documentation/sort_glossary.pl +++ b/Documentation/sort_glossary.pl @@ -48,7 +48,7 @@ This list is sorted alphabetically: '; @keys=sort {uc($a) cmp uc($b)} keys %terms; -$pattern='(\b'.join('\b|\b',reverse @keys).'\b)'; +$pattern='(\b(?<!link:git-)'.join('\b|\b(?<!link:git-)',reverse @keys).'\b)'; foreach $key (@keys) { $terms{$key}=~s/$pattern/sprintf "<<ref_".no_spaces($1).",$1>>";/eg; print '[[ref_'.no_spaces($key).']]'.$key."::\n" |