From: Junio C Hamano Date: Wed, 22 Aug 2012 18:52:55 +0000 (-0700) Subject: Merge branch 'jc/tag-doc' X-Git-Tag: v1.8.0-rc0~145 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/7e0c2036b46ee6eef295a7e6dcb3775e874aa780?ds=inline;hp=-c Merge branch 'jc/tag-doc' Our documentation used to assume having files in .git/refs/* directories was the only to have branches and tags, but that is not true for quite some time. * jc/tag-doc: Documentation: do not mention .git/refs/* directories --- 7e0c2036b46ee6eef295a7e6dcb3775e874aa780 diff --combined Documentation/git-filter-branch.txt index 81f58234a7,924a38c96c..15e7ac80c0 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@@ -32,7 -32,8 +32,8 @@@ changes, which would normally have no e useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. - *NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. + *NOTE*: This command honors `.git/info/grafts` file and refs in + the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. @@@ -96,8 -97,8 +97,8 @@@ OPTION --index-filter :: This is the filter for rewriting the index. It is similar to the tree filter but does not check out the tree, which makes it much - faster. Frequently used with `git rm \--cached - \--ignore-unmatch ...`, see EXAMPLES below. For hairy + faster. Frequently used with `git rm --cached + --ignore-unmatch ...`, see EXAMPLES below. For hairy cases, see linkgit:git-update-index[1]. --parent-filter :: @@@ -222,11 -223,11 +223,11 @@@ However, if the file is absent from th a simple `rm filename` will fail for that tree and commit. Thus you may instead want to use `rm -f filename` as the script. -Using `\--index-filter` with 'git rm' yields a significantly faster +Using `--index-filter` with 'git rm' yields a significantly faster version. Like with using `rm filename`, `git rm --cached filename` will fail if the file is absent from the tree of a commit. If you want to "completely forget" a file, it does not matter when it entered -history, so we also add `\--ignore-unmatch`: +history, so we also add `--ignore-unmatch`: -------------------------------------------------------------------------- git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD @@@ -242,8 -243,8 +243,8 @@@ git filter-branch --subdirectory-filte ------------------------------------------------------- Thus you can, e.g., turn a library subdirectory into a repository of -its own. Note the `\--` that separates 'filter-branch' options from -revision options, and the `\--all` to rewrite all branches and tags. +its own. Note the `--` that separates 'filter-branch' options from +revision options, and the `--all` to rewrite all branches and tags. To set a commit (which typically is at the tip of another history) to be the parent of the current initial commit, in @@@ -371,23 -372,23 +372,23 @@@ Checklist for Shrinking a Repositor ------------------------------------ git-filter-branch is often used to get rid of a subset of files, -usually with some combination of `\--index-filter` and -`\--subdirectory-filter`. People expect the resulting repository to +usually with some combination of `--index-filter` and +`--subdirectory-filter`. People expect the resulting repository to be smaller than the original, but you need a few more steps to actually make it smaller, because git tries hard not to lose your objects until you tell it to. First make sure that: * You really removed all variants of a filename, if a blob was moved - over its lifetime. `git log \--name-only \--follow \--all \-- - filename` can help you find renames. + over its lifetime. `git log --name-only --follow --all -- filename` + can help you find renames. -* You really filtered all refs: use `\--tag-name-filter cat \-- - \--all` when calling git-filter-branch. +* You really filtered all refs: use `--tag-name-filter cat -- --all` + when calling git-filter-branch. Then there are two ways to get a smaller repository. A safer way is to clone, that keeps your original intact. -* Clone it with `git clone +++file:///path/to/repo+++`. The clone +* Clone it with `git clone file:///path/to/repo`. The clone will not have the removed objects. See linkgit:git-clone[1]. (Note that cloning with a plain path just hardlinks everything!) @@@ -397,14 -398,14 +398,14 @@@ approach, so *make a backup* or go bac warned. * Remove the original refs backed up by git-filter-branch: say `git - for-each-ref \--format="%(refname)" refs/original/ | xargs -n 1 git + for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d`. -* Expire all reflogs with `git reflog expire \--expire=now \--all`. +* Expire all reflogs with `git reflog expire --expire=now --all`. -* Garbage collect all unreferenced objects with `git gc \--prune=now` +* Garbage collect all unreferenced objects with `git gc --prune=now` (or if your git-gc is not new enough to support arguments to - `\--prune`, use `git repack -ad; git prune` instead). + `--prune`, use `git repack -ad; git prune` instead). GIT --- diff --combined Documentation/git-fsck.txt index bbb25da2dd,df9ea8df0b..da348fc942 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@@ -11,7 -11,7 +11,7 @@@ SYNOPSI [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]progress] [*] + [--[no-]dangling] [--[no-]progress] [*] DESCRIPTION ----------- @@@ -23,18 -23,13 +23,18 @@@ OPTION An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the - index file, all SHA1 references in .git/refs/*, and all reflogs (unless - --no-reflogs is given) as heads. + index file, all SHA1 references in `refs` namespace, and all reflogs + (unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any of the reference nodes. +--dangling:: +--no-dangling:: + Print objects that exist but that are never 'directly' used (default). + `--no-dangling` can be used to omit this information from the output. + --root:: Report root nodes. diff --combined Documentation/git-pack-refs.txt index 10afd4edfe,7664bd1741..f131677478 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@@ -14,7 -14,8 +14,8 @@@ DESCRIPTIO ----------- Traditionally, tips of branches and tags (collectively known as - 'refs') were stored one file per ref under `$GIT_DIR/refs` + 'refs') were stored one file per ref in a (sub)directory + under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@@ -22,17 -23,18 +23,18 @@@ one-file-per-ref format both wastes sto performance. This command is used to solve the storage and performance - problem by stashing the refs in a single file, + problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the - traditional `$GIT_DIR/refs` hierarchy, it is looked up in this + traditional `$GIT_DIR/refs` directory hierarchy, it is looked + up in this file and used if found. Subsequent updates to branches always create new files under - `$GIT_DIR/refs` hierarchy. + `$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and -occasionally run `git pack-refs \--prune`. Tags are by +occasionally run `git pack-refs --prune`. Tags are by definition stationary and are not expected to change. Branch heads will be packed with the initial `pack-refs --all`, but only the currently active branch heads will become unpacked, @@@ -57,6 -59,15 +59,15 @@@ a repository with many branches of hist The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + + BUGS + ---- + + Older documentation written before the packed-refs mechanism was + introduced may still say things like ".git/refs/heads/ file + exists" when it means "branch exists". + + GIT --- Part of the linkgit:git[1] suite diff --combined Documentation/git-tag.txt index e36a7c3d1e,f7abf0bca7..247534e908 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@@ -12,19 -12,16 +12,18 @@@ SYNOPSI 'git tag' [-a | -s | -u ] [-f] [-m | -F ] [ | ] 'git tag' -d ... -'git tag' [-n[]] -l [--contains ] [...] +'git tag' [-n[]] -l [--contains ] [--points-at ] + [--column[=] | --no-column] [...] + [...] 'git tag' -v ... DESCRIPTION ----------- - Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given + Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. - Unless `-f` is given, the tag to be created must not yet exist in the - `.git/refs/tags/` directory. + Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u ` is passed, the command creates a 'tag' object, and requires a tag message. Unless @@@ -85,20 -82,9 +84,20 @@@ OPTION using fnmatch(3)). Multiple patterns may be given; if any of them matches, the tag is shown. +--column[=]:: +--no-column:: + Display tag listing in columns. See configuration variable + column.tag for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable when listing tags without annotation lines. + --contains :: Only list tags which contain the specified commit. +--points-at :: + Only list tags of the given object. + -m :: --message=:: Use the given tag message (instead of prompting).