cvsserver: add comments about database schema/usage
No functionality changes, but these comments should make it easier to understand how it works. Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthew Ogilvie committed
Oct 13, 2012 at 23:42 UTC
196e48f4d0bac31f4a56b7dc4816f813cc17ad13
1 file changed
+42
-4
git-cvsserver.perl
+42
-4
@@ -2129,6 +2129,10 @@ sub statecleanup
2129
$state->{entries} = {};
2130
}
2131
2132
+# Return working directory revision int "X" from CVS revision "1.X" out
2133
+# of the the working directory "entries" state, for the given filename.
2134
+# Return negative "X" to represent the file is scheduled for removal
2135
+# when it is committed.
2136
sub revparse
2137
{
2138
my $filename = shift;
@@ -2901,6 +2905,16 @@ sub new
2905
}
2906
2907
# Construct the revision table if required
2908
+ # The revision table stores an entry for each file, each time that file
2909
+ # changes.
2910
+ # numberOfRecords = O( numCommits * averageNumChangedFilesPerCommit )
2911
+ # This is not sufficient to support "-r {commithash}" for any
2912
+ # files except files that were modified by that commit (also,
2913
+ # some places in the code ignore/effectively strip out -r in
2914
+ # some cases, before it gets passed to getmeta()).
2915
+ # The "filehash" field typically has a git blob hash, but can also
2916
+ # be set to "dead" to indicate that the given version of the file
2917
+ # should not exist in the sandbox.
2918
unless ( $self->{tables}{$self->tablename("revision")} )
2919
{
2920
my $tablename = $self->tablename("revision");
@@ -2928,6 +2942,15 @@ sub new
2942
}
2943
2944
# Construct the head table if required
2945
+ # The head table (along with the "last_commit" entry in the property
2946
+ # table) is the persisted working state of the "sub update" subroutine.
2947
+ # All of it's data is read entirely first, and completely recreated
2948
+ # last, every time "sub update" runs.
2949
+ # This is also used by "sub getmeta" when it is asked for the latest
2950
+ # version of a file (as opposed to some specific version).
2951
+ # Another way of thinking about it is as a single slice out of
2952
+ # "revisions", giving just the most recent revision information for
2953
+ # each file.
2954
unless ( $self->{tables}{$self->tablename("head")} )
2955
{
2956
my $tablename = $self->tablename("head");
@@ -2950,6 +2973,7 @@ sub new
2973
}
2974
2975
# Construct the properties table if required
2976
+ # - "last_commit" - Used by "sub update".
2977
unless ( $self->{tables}{$self->tablename("properties")} )
2978
{
2979
my $tablename = $self->tablename("properties");
@@ -2962,6 +2986,11 @@ sub new
2986
}
2987
2988
# Construct the commitmsgs table if required
2989
+ # The commitmsgs table is only used for merge commits, since
2990
+ # "sub update" will only keep one branch of parents. Shortlogs
2991
+ # for ignored commits (i.e. not on the chosen branch) will be used
2992
+ # to construct a replacement "collapsed" merge commit message,
2993
+ # which will be stored in this table. See also "sub commitmessage".
2994
unless ( $self->{tables}{$self->tablename("commitmsgs")} )
2995
{
2996
my $tablename = $self->tablename("commitmsgs");
@@ -2993,6 +3022,14 @@ sub tablename
3022
3023
=head2 update
3024
3025
+Bring the database up to date with the latest changes from
3026
+the git repository.
3027
+
3028
+Internal working state is read out of the "head" table and the
3029
+"last_commit" property, then it updates "revisions" based on that, and
3030
+finally it writes the new internal state back to the "head" table
3031
+so it can be used as a starting point the next time update is called.
3032
+
3033
=cut
3034
sub update
3035
{
@@ -3106,17 +3143,18 @@ sub update
3143
next;
3144
} elsif (@{$commit->{parents}} > 1) {
3145
# it is a merge commit, for each parent that is
3109
- # not $lastpicked, see if we can get a log
3146
+ # not $lastpicked (not given a CVS revision number),
3147
+ # see if we can get a log
3148
# from the merge-base to that parent to put it
3149
# in the message as a merge summary.
3150
my @parents = @{$commit->{parents}};
3151
foreach my $parent (@parents) {
3114
- # git-merge-base can potentially (but rarely) throw
3115
- # several candidate merge bases. let's assume
3116
- # that the first one is the best one.
3152
if ($parent eq $lastpicked) {
3153
next;
3154
}
3155
+ # git-merge-base can potentially (but rarely) throw
3156
+ # several candidate merge bases. let's assume
3157
+ # that the first one is the best one.
3158
my $base = eval {
3159
safe_pipe_capture('git', 'merge-base',
3160
$lastpicked, $parent);