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