compat/fnmatch: update old-style definition to ANSI
[git/git.git] / Documentation / howto / update-hook-example.txt
1 From: Junio C Hamano <gitster@pobox.com> and Carl Baldwin <cnb@fc.hp.com>
2 Subject: control access to branches.
3 Date: Thu, 17 Nov 2005 23:55:32 -0800
4 Message-ID: <7vfypumlu3.fsf@assigned-by-dhcp.cox.net>
5 Abstract: An example hooks/update script is presented to
6 implement repository maintenance policies, such as who can push
7 into which branch and who can make a tag.
8
9 When your developer runs git-push into the repository,
10 git-receive-pack is run (either locally or over ssh) as that
11 developer, so is hooks/update script. Quoting from the relevant
12 section of the documentation:
13
14 Before each ref is updated, if $GIT_DIR/hooks/update file exists
15 and executable, it is called with three parameters:
16
17 $GIT_DIR/hooks/update refname sha1-old sha1-new
18
19 The refname parameter is relative to $GIT_DIR; e.g. for the
20 master head this is "refs/heads/master". Two sha1 are the
21 object names for the refname before and after the update. Note
22 that the hook is called before the refname is updated, so either
23 sha1-old is 0{40} (meaning there is no such ref yet), or it
24 should match what is recorded in refname.
25
26 So if your policy is (1) always require fast-forward push
27 (i.e. never allow "git-push repo +branch:branch"), (2) you
28 have a list of users allowed to update each branch, and (3) you
29 do not let tags to be overwritten, then you can use something
30 like this as your hooks/update script.
31
32 [jc: editorial note. This is a much improved version by Carl
33 since I posted the original outline]
34
35 -- >8 -- beginning of script -- >8 --
36
37 #!/bin/bash
38
39 umask 002
40
41 # If you are having trouble with this access control hook script
42 # you can try setting this to true. It will tell you exactly
43 # why a user is being allowed/denied access.
44
45 verbose=false
46
47 # Default shell globbing messes things up downstream
48 GLOBIGNORE=*
49
50 function grant {
51 $verbose && echo >&2 "-Grant- $1"
52 echo grant
53 exit 0
54 }
55
56 function deny {
57 $verbose && echo >&2 "-Deny- $1"
58 echo deny
59 exit 1
60 }
61
62 function info {
63 $verbose && echo >&2 "-Info- $1"
64 }
65
66 # Implement generic branch and tag policies.
67 # - Tags should not be updated once created.
68 # - Branches should only be fast-forwarded unless their pattern starts with '+'
69 case "$1" in
70 refs/tags/*)
71 git rev-parse --verify -q "$1" &&
72 deny >/dev/null "You can't overwrite an existing tag"
73 ;;
74 refs/heads/*)
75 # No rebasing or rewinding
76 if expr "$2" : '0*$' >/dev/null; then
77 info "The branch '$1' is new..."
78 else
79 # updating -- make sure it is a fast-forward
80 mb=$(git-merge-base "$2" "$3")
81 case "$mb,$2" in
82 "$2,$mb") info "Update is fast-forward" ;;
83 *) noff=y; info "This is not a fast-forward update.";;
84 esac
85 fi
86 ;;
87 *)
88 deny >/dev/null \
89 "Branch is not under refs/heads or refs/tags. What are you trying to do?"
90 ;;
91 esac
92
93 # Implement per-branch controls based on username
94 allowed_users_file=$GIT_DIR/info/allowed-users
95 username=$(id -u -n)
96 info "The user is: '$username'"
97
98 if test -f "$allowed_users_file"
99 then
100 rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' |
101 while read heads user_patterns
102 do
103 # does this rule apply to us?
104 head_pattern=${heads#+}
105 matchlen=$(expr "$1" : "${head_pattern#+}")
106 test "$matchlen" = ${#1} || continue
107
108 # if non-ff, $heads must be with the '+' prefix
109 test -n "$noff" &&
110 test "$head_pattern" = "$heads" && continue
111
112 info "Found matching head pattern: '$head_pattern'"
113 for user_pattern in $user_patterns; do
114 info "Checking user: '$username' against pattern: '$user_pattern'"
115 matchlen=$(expr "$username" : "$user_pattern")
116 if test "$matchlen" = "${#username}"
117 then
118 grant "Allowing user: '$username' with pattern: '$user_pattern'"
119 fi
120 done
121 deny "The user is not in the access list for this branch"
122 done
123 )
124 case "$rc" in
125 grant) grant >/dev/null "Granting access based on $allowed_users_file" ;;
126 deny) deny >/dev/null "Denying access based on $allowed_users_file" ;;
127 *) ;;
128 esac
129 fi
130
131 allowed_groups_file=$GIT_DIR/info/allowed-groups
132 groups=$(id -G -n)
133 info "The user belongs to the following groups:"
134 info "'$groups'"
135
136 if test -f "$allowed_groups_file"
137 then
138 rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' |
139 while read heads group_patterns
140 do
141 # does this rule apply to us?
142 head_pattern=${heads#+}
143 matchlen=$(expr "$1" : "${head_pattern#+}")
144 test "$matchlen" = ${#1} || continue
145
146 # if non-ff, $heads must be with the '+' prefix
147 test -n "$noff" &&
148 test "$head_pattern" = "$heads" && continue
149
150 info "Found matching head pattern: '$head_pattern'"
151 for group_pattern in $group_patterns; do
152 for groupname in $groups; do
153 info "Checking group: '$groupname' against pattern: '$group_pattern'"
154 matchlen=$(expr "$groupname" : "$group_pattern")
155 if test "$matchlen" = "${#groupname}"
156 then
157 grant "Allowing group: '$groupname' with pattern: '$group_pattern'"
158 fi
159 done
160 done
161 deny "None of the user's groups are in the access list for this branch"
162 done
163 )
164 case "$rc" in
165 grant) grant >/dev/null "Granting access based on $allowed_groups_file" ;;
166 deny) deny >/dev/null "Denying access based on $allowed_groups_file" ;;
167 *) ;;
168 esac
169 fi
170
171 deny >/dev/null "There are no more rules to check. Denying access"
172
173 -- >8 -- end of script -- >8 --
174
175 This uses two files, $GIT_DIR/info/allowed-users and
176 allowed-groups, to describe which heads can be pushed into by
177 whom. The format of each file would look like this:
178
179 refs/heads/master junio
180 +refs/heads/pu junio
181 refs/heads/cogito$ pasky
182 refs/heads/bw/.* linus
183 refs/heads/tmp/.* .*
184 refs/tags/v[0-9].* junio
185
186 With this, Linus can push or create "bw/penguin" or "bw/zebra"
187 or "bw/panda" branches, Pasky can do only "cogito", and JC can
188 do master and pu branches and make versioned tags. And anybody
189 can do tmp/blah branches. The '+' sign at the pu record means
190 that JC can make non-fast-forward pushes on it.
191
192 ------------