From: Johan Herland Date: Sat, 09 Jun 2007 18:23:13 GMT Subject: [PATCH 4/7] Softrefs: Add manual page documenting git-softref and softrefs subsystem in general Message-ID: <200706092023.13537.johan@herland.net> In-Reply-To: <200706092019.13185.johan@herland.net> Signed-off-by: Johan Herland --- Documentation/git-softref.txt | 119 +++++++++++++++++++++++++++++++++++++++++ 1 files changed, 119 insertions(+), 0 deletions(-) create mode 100644 Documentation/git-softref.txt diff --git a/Documentation/git-softref.txt b/Documentation/git-softref.txt new file mode 100644 index 0000000..6a3e13b --- /dev/null +++ b/Documentation/git-softref.txt @@ -0,0 +1,119 @@ +git-softref(1) +============== + +NAME +---- +git-softref - Create, list and administer soft references + + +SYNOPSIS +-------- +[verse] +'git-softref' --list [] +'git-softref' --has +'git-softref' --add +'git-softref' --rebuild-tags +'git-softref' --merge-unsorted [] +'git-softref' --merge-sorted + + +DESCRIPTION +----------- +Query and administer soft references in a git repository. + +Soft references are used to declare reachability between already existing +objects. An object (called the 'to-object') may be declared reachable from +another object (the 'from-object') without affecting the immutability of either +object. + +The `--list` option will list existing softrefs in the database. If given the +optional , the list is limited to softrefs from the given object. +The `--has` option is used to check for the existence of a softref between two +given objects, similarly the `--add` option is used to add such a softref. + +The `--rebuild-tags` option is used to generate softrefs for all tag objects in +the repository reachable from tag refs. Tag objects use softrefs to declare +reachability 'from' the tagged object, 'to' the tag object. This allows for tag +objects to the cloned/fetched/pushed along with their associated objects. + +Finally, the `--merge-unsorted` and `--merge-sorted` options are used to merge +softrefs files into the sorted softrefs db. The filename argument must point +to an existing file in unsorted/sorted softrefs format. The softrefs entries +in this file will be merged into the sorted softrefs db. The `--merge-unsorted` +option may be used 'without' a filename, in which case the currently unsorted +portion of the softrefs db will be merged into the sorted db. Note that this +last operation is also done regularly by default when adding softrefs, so +there is no need to invoke this option during regular use. + + +OPTIONS +------- +--list []:: + List all softrefs that have the given ''. + If '' is not given, list 'all' softrefs in the repository. + +--has :: + Return with exit code 1 if the given softref exists in the repository. + Return with exit code 0 otherwise. + +--add :: + Add a softref from the given '' to the given ''. + The '' will from now on be considered reachable from the + ''. + +--rebuild-tags:: + Automatically generate softrefs for all tag objects reachable from + tag refs in the repository. + +--merge-unsorted []:: + Merge the softrefs in the given unsorted '' into the + sorted softrefs db. If a filename is not given, force a merge of the + internal unsorted softrefs store into the sorted softrefs db. + +--merge-sorted :: + Merge the softrefs in the given sorted '' into the + sorted softrefs db. + + +DISCUSSION +---------- +Soft references (softrefs) is a general mechanism for declaring a relationship +between two existing arbitrary objects in the repo. Softrefs differ from the +existing reachability relationship in that a softref may be created after +'both' of the involved objects have been added to the repo. In contrast, +regular reachability depends on the reachable object's name being stored +'inside' the other object. A reachability relationship can therefore not be +created at a later time without violating the immutability of git objects. + +Softrefs are defined as going 'from' one object 'to' another object. Once +a softref between two objects has been created, the "to" object is considered +reachable from the "from" object. + +Also, softrefs are stored in a way that makes it easy and quick to find all +the "to" objects reachable from a given "from" object. + +The softrefs db consists of two files: `.git/softrefs.unsorted` and +`.git/softrefs.sorted`. Both files use the same format; one softref per line +of the form "` \n`". Each sha1 sum is 40 bytes long; this +makes each entry exactly 82 bytes long. + +The entries in `.git/softrefs.sorted` are sorted on ``, in order to +make lookup fast. This file is also known as the "sorted softrefs db". + +The entries in `.git/softrefs.unsorted` are 'not' sorted. This is to make +insertion fast. This file is also known as the "unsorted softrefs db". + +When softrefs are created, they are appended to `.git/softrefs.unsorted`. +When `.git/softrefs.unsorted` reach a certain number of entries, all the +entries in `.git/softrefs.unsorted` are automatically merged into +`.git/softrefs.sorted`. + + +Author +------ +Written by Johan Herland . + + +GIT +--- +Part of the gitlink:git[7] suite -- 1.5.2.1.144.gabc40