Signed-off-by: Johan Herland <johan@xxxxxxxxxxx> --- 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 [<from-object>] +'git-softref' --has <from-object> <to-object> +'git-softref' --add <from-object> <to-object> +'git-softref' --rebuild-tags +'git-softref' --merge-unsorted [<softrefs-file>] +'git-softref' --merge-sorted <softrefs-file> + + +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 <from-object>, 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 [<from-object>]:: + List all softrefs that have the given '<from-object>'. + If '<from-object>' is not given, list 'all' softrefs in the repository. + +--has <from-object> <to-object>:: + Return with exit code 1 if the given softref exists in the repository. + Return with exit code 0 otherwise. + +--add <from-object> <to-object>:: + Add a softref from the given '<from-object>' to the given '<to-object>'. + The '<to-object>' will from now on be considered reachable from the + '<from-object>'. + +--rebuild-tags:: + Automatically generate softrefs for all tag objects reachable from + tag refs in the repository. + +--merge-unsorted [<softrefs-file>]:: + Merge the softrefs in the given unsorted '<softrefs-file>' 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 <softrefs-file>:: + Merge the softrefs in the given sorted '<softrefs-file>' 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 "`<from-sha1> <to-sha1>\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 `<from-sha1>`, 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 <johan@xxxxxxxxxxx>. + + +GIT +--- +Part of the gitlink:git[7] suite -- 1.5.2.1.144.gabc40 - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
