Mercurial > hgbook
changeset 382:d64d38d2a91a
more hook.tex
| author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
|---|---|
| date | Thu, 19 Feb 2009 20:42:55 +0900 |
| parents | 991befd0025c |
| children | ef0c1fb05c84 |
| files | ja/hook.tex ja/todo.txt |
| diffstat | 2 files changed, 188 insertions(+), 92 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/hook.tex Thu Feb 19 14:59:58 2009 +0900 +++ b/ja/hook.tex Thu Feb 19 20:42:55 2009 +0900 @@ -718,42 +718,71 @@ %\subsection{Telling Mercurial to use an in-process hook} \subsection{Mercurial$B$K%W%m%;%9Fb%U%C%/$r;H$&$h$&$K;X<($9$k(B} -The \hgrc\ syntax for defining an in-process hook is slightly -different than for an executable hook. The value of the hook must -start with the text ``\texttt{python:}'', and continue with the -fully-qualified name of a callable object to use as the hook's value. +%The \hgrc\ syntax for defining an in-process hook is slightly +%different than for an executable hook. The value of the hook must +%start with the text ``\texttt{python:}'', and continue with the +%fully-qualified name of a callable object to use as the hook's value. + +$B%W%m%;%9$J$$%U%C%/$rDj5A$9$k(B \hgrc\ $B9=J8$O<B9T2DG=%U%C%/$H$O6O$+$K0[$J$C(B +$B$F$$$k!%%U%C%/$NCM$OI,$:(B``\texttt{python:}''$B$G;O$^$j!$8e$K%U%C%/CM$H$7$F(B +$BMQ$$$i$l$k8F=P$72DG=%*%V%8%'%/%H$N40A4$JL>A0$,B3$+$J$1$l$P$J$i$J$$!%(B + +%The module in which a hook lives is automatically imported when a hook +%is run. So long as you have the module name and \envar{PYTHONPATH} +%right, it should ``just work''. -The module in which a hook lives is automatically imported when a hook -is run. So long as you have the module name and \envar{PYTHONPATH} -right, it should ``just work''. +$B%U%C%/$,4^$^$l$k%b%8%e!<%k$O%U%C%/$,<B9T$5$l$k;~$K<+F0E*$KFI$_9~$^$l$k!%(B +$B%b%8%e!<%kL>$*$h$S(B\envar{PYTHONPATH}$B$,@5$7$$$+$.$jI,$:F0:n$9$k$O$:$G$"$k!%(B -The following \hgrc\ example snippet illustrates the syntax and -meaning of the notions we just described. +%The following \hgrc\ example snippet illustrates the syntax and +%meaning of the notions we just described. +%\begin{codesample2} +% [hooks] +% commit.example = python:mymodule.submodule.myhook +%\end{codesample2} +%When Mercurial runs the \texttt{commit.example} hook, it imports +%\texttt{mymodule.submodule}, looks for the callable object named +%\texttt{myhook}, and calls it. + +$B:#@bL@$7$?9=J8$H35G0$r@bL@$9$kCGJRE*$JNc$r0J2<$N(B\hgrc\ $B$K<($9!%(B \begin{codesample2} [hooks] commit.example = python:mymodule.submodule.myhook \end{codesample2} -When Mercurial runs the \texttt{commit.example} hook, it imports -\texttt{mymodule.submodule}, looks for the callable object named -\texttt{myhook}, and calls it. +Mercurial$B$,(B\texttt{commit.example}$B%U%C%/$r<B9T$9$k;~!$(B +\texttt{mymodule.submodule}$B$rFI$_9~$_!$8F=P$72DG=%*%V%8%'%/%H(B +\texttt{myhook}$B$rC5$7!$<B9T$9$k!%(B %\subsection{Writing an in-process hook} \subsection{$B%W%m%;%9Fb%U%C%/$r:n@.$9$k(B} -The simplest in-process hook does nothing, but illustrates the basic -shape of the hook API: +%The simplest in-process hook does nothing, but illustrates the basic +%shape of the hook API: +%\begin{codesample2} +% def myhook(ui, repo, **kwargs): +% pass +%\end{codesample2} +%The first argument to a Python hook is always a +%\pymodclass{mercurial.ui}{ui} object. The second is a repository object; +%at the moment, it is always an instance of +%\pymodclass{mercurial.localrepo}{localrepository}. Following these two +%arguments are other keyword arguments. Which ones are passed in +%depends on the hook being called, but a hook can ignore arguments it +%doesn't care about by dropping them into a keyword argument dict, as +%with \texttt{**kwargs} above. + +$B<B:]$K$O2?$b9T$o$J$$:G$bC1=c$J%W%m%;%9Fb%U%C%/$r%U%C%/(BAPI$B$N4pK\E*$J;H$$J}(B +$B$r@bL@$9$k$?$a$K<($9!%(B \begin{codesample2} def myhook(ui, repo, **kwargs): pass \end{codesample2} -The first argument to a Python hook is always a -\pymodclass{mercurial.ui}{ui} object. The second is a repository object; -at the moment, it is always an instance of -\pymodclass{mercurial.localrepo}{localrepository}. Following these two -arguments are other keyword arguments. Which ones are passed in -depends on the hook being called, but a hook can ignore arguments it -doesn't care about by dropping them into a keyword argument dict, as -with \texttt{**kwargs} above. +Python$B%U%C%/$X$N:G=i$N0z?t$O>o$K(B\pymodclass{mercurial.ui}{ui}$B%*%V%8%'%/%H(B +$B$G$"$k!%(B2$BHVL\$N0z?t$O%j%]%8%H%j%*%V%8%'%/%H$G!$8=:_$N$H$3$m>o$K(B +\pymodclass{mercurial.localrepo}{localrepository}$B$N%$%s%9%?%s%9$G$"$k!%B>(B +$B$N%-!<%o!<%I0z?t$O$3$l$i$N(B2$B$D$N0z?t$KB3$/!%$3$l$i$O8F$S=P$5$l$F$$$k%U%C%/(B +$B$K0MB8$9$k$,!$%U%C%/$O%-!<%o!<%I$N<-=q$K(B\texttt{**kwargs}$B$H5-=R$9$k$3$H(B +$B$G!$I,MW$N$J$$0z?t$rL5;k$9$k$3$H$b$G$-$k!%(B %\section{Some hook examples} \section{$B%U%C%/$NNc(B} @@ -761,81 +790,132 @@ %\subsection{Writing meaningful commit messages} \subsection{$B0UL#$N$"$k%3%_%C%H%a%C%;!<%8$r=PNO$9$k(B} -It's hard to imagine a useful commit message being very short. The -simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go} -will prevent you from committing a changeset with a message that is -less than ten bytes long. +%It's hard to imagine a useful commit message being very short. The +%simple \hook{pretxncommit} hook of figure~\ref{ex:hook:msglen.go} +%will prevent you from committing a changeset with a message that is +%less than ten bytes long. + +$BHs>o$KC;$$%3%_%C%H%a%C%;!<%8$,M-MQ$G$"$k$3$H$O$^$:$J$$!%(B +$B?^(B~\ref{ex:hook:msglen.go}$B$K<($9(B\hook{pretxncommit}$B$H$$$&C1=c$J%U%C%/$O(B10 +$B%P%$%H0J2<$ND9$5$N%3%_%C%H%a%C%;!<%8$G%3%_%C%H$r9T$&$3$H$r6X;_$9$k!%(B \begin{figure}[ht] \interaction{hook.msglen.go} - \caption{A hook that forbids overly short commit messages} +% \caption{A hook that forbids overly short commit messages} + \caption{$B6KC<$KC;$$%3%_%C%H%a%C%;!<%8$r6X;_$9$k%U%C%/(B} \label{ex:hook:msglen.go} \end{figure} %\subsection{Checking for trailing whitespace} \subsection{$B$V$i2<$,$C$?6uGr$r%A%'%C%/$9$k(B} -An interesting use of a commit-related hook is to help you to write -cleaner code. A simple example of ``cleaner code'' is the dictum that -a change should not add any new lines of text that contain ``trailing -whitespace''. Trailing whitespace is a series of space and tab -characters at the end of a line of text. In most cases, trailing -whitespace is unnecessary, invisible noise, but it is occasionally -problematic, and people often prefer to get rid of it. +%An interesting use of a commit-related hook is to help you to write +%cleaner code. A simple example of ``cleaner code'' is the dictum that +%a change should not add any new lines of text that contain ``trailing +%whitespace''. Trailing whitespace is a series of space and tab +%characters at the end of a line of text. In most cases, trailing +%whitespace is unnecessary, invisible noise, but it is occasionally +%problematic, and people often prefer to get rid of it. + +$B%3%_%C%H$K4XO"$7$?%U%C%/$N6=L#?<$$;HMQK!$N0l$D$K$h$j4qNo$J%3!<%I$r=q$/<j(B +$B=u$1$,$"$k!%(B ``$B4qNo$J%3!<%I(B''$B$N$4$/C1=c$JNc$O!$Nc$($P!$?7$?$J$V$i2<$,$C$?(B +$B6uGr$r4^$`9T$r4^$^$J$$$b$N$G$"$k!%$V$i2<$,$C$?6uGr$H$O!$9TKv$N0lO"$N%9%Z!<(B +$B%9$d%?%V$G$"$k!%$[$H$s$I$N>l9g!$$V$i2<$,$C$?6uGr$OITI,MW$J8+$($J$$%N%$%:(B +$B$G$"$k$,!$LdBj$r0z$-5/$3$9>l9g$b$"$j!$=|5n$7$?$,$k?M$,B?$$!%(B + +%You can use either the \hook{precommit} or \hook{pretxncommit} hook to +%tell whether you have a trailing whitespace problem. If you use the +%\hook{precommit} hook, the hook will not know which files you are +%committing, so it will have to check every modified file in the +%repository for trailing white space. If you want to commit a change +%to just the file \filename{foo}, but the file \filename{bar} contains +%trailing whitespace, doing a check in the \hook{precommit} hook will +%prevent you from committing \filename{foo} due to the problem with +%\filename{bar}. This doesn't seem right. -You can use either the \hook{precommit} or \hook{pretxncommit} hook to -tell whether you have a trailing whitespace problem. If you use the -\hook{precommit} hook, the hook will not know which files you are -committing, so it will have to check every modified file in the -repository for trailing white space. If you want to commit a change -to just the file \filename{foo}, but the file \filename{bar} contains -trailing whitespace, doing a check in the \hook{precommit} hook will -prevent you from committing \filename{foo} due to the problem with -\filename{bar}. This doesn't seem right. +$B$V$i2<$,$j6uGr$NLdBj$rD>$9$?$a$K(B\hook{precommit}$B%U%C%/$d(B +\hook{pretxncommit}$B%U%C%/$rMQ$$$k$3$H$,$G$-$k!%(B\hook{precommit}$B%U%C%/$r;H(B +$B$&>l9g!$$I$N%U%!%$%k$r%3%_%C%H$9$k$N$+%U%C%/$OCN$k$3$H$,$J$$!%$=$N$?$a!$(B +$B%j%]%8%H%j$GJQ99$5$l$?%U%!%$%k$9$Y$F$K$D$$$F$V$i2<$,$j6uGr$r%A%'%C%/$9$k(B +$BI,MW$,$"$k!%(B \filename{foo}$B$H$$$&%U%!%$%k$r%3%_%C%H$7$?$$(B +$B$,!$(B\filename{bar}$B%U%!%$%k$,$V$i2<$,$j6uGr$r4^$s$G$$$k>l(B +$B9g!$(B\hook{precommit}$B%U%C%/$G%A%'%C%/$r9T$&$H!$%U%!%$%k(B\filename{bar}$B$NLd(B +$BBj$N$?$a$K(B\filename{foo}$B$N%3%_%C%H$,$G$-$J$/$J$k!%$3$l$O@5$7$$5sF0$H$O8@(B +$B$($J$$!%(B -Should you choose the \hook{pretxncommit} hook, the check won't occur -until just before the transaction for the commit completes. This will -allow you to check for problems only the exact files that are being -committed. However, if you entered the commit message interactively -and the hook fails, the transaction will roll back; you'll have to -re-enter the commit message after you fix the trailing whitespace and -run \hgcmd{commit} again. +%Should you choose the \hook{pretxncommit} hook, the check won't occur +%until just before the transaction for the commit completes. This will +%allow you to check for problems only the exact files that are being +%committed. However, if you entered the commit message interactively +%and the hook fails, the transaction will roll back; you'll have to +%re-enter the commit message after you fix the trailing whitespace and +%run \hgcmd{commit} again. + +\hook{pretxncommit}$B%U%C%/$rA*$S!$%A%'%C%/$,%3%_%C%H40N;%H%i%s%6%/%7%g%s$N(B +$BD>A0$^$G5/$-$J$$$h$&$K$9$Y$-$G$"$k!%$3$l$K$h$j!$%3%_%C%H$5$l$h$&$H$9$k%U%!(B +$B%$%k$@$1$r%A%'%C%/$9$k$3$H$,$G$-$k$h$&$K$J$k!%$7$+$7$J$,$i!$%3%_%C%H%a%C(B +$B%;!<%8$rBPOCE*$KF~NO$7!$%3%_%C%H$,<:GT$9$k$H%H%i%s%6%/%7%g%s$O%m!<%k%P%C(B +$B%/$9$k$?$a!$$V$i2<$,$j6uGr$r=$@5$7!$(B\hgcmd{commit}$B$r:F$S<B9T$7!$%3%_%C%H(B +$B$9$k:]$K%3%_%C%H%a%C%;!<%8$r:FF~NO$7$J$1$l$P$J$i$J$$!%(B \begin{figure}[ht] \interaction{hook.ws.simple} - \caption{A simple hook that checks for trailing whitespace} +% \caption{A simple hook that checks for trailing whitespace} + \caption{$B$V$i2<$,$C$?6uGr$r%A%'%C%/$9$kC1=c$J%U%C%/(B} \label{ex:hook:ws.simple} \end{figure} -Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit} -hook that checks for trailing whitespace. This hook is short, but not -very helpful. It exits with an error status if a change adds a line -with trailing whitespace to any file, but does not print any -information that might help us to identify the offending file or -line. It also has the nice property of not paying attention to -unmodified lines; only lines that introduce new trailing whitespace -cause problems. +%Figure~\ref{ex:hook:ws.simple} introduces a simple \hook{pretxncommit} +%hook that checks for trailing whitespace. This hook is short, but not +%very helpful. It exits with an error status if a change adds a line +%with trailing whitespace to any file, but does not print any +%information that might help us to identify the offending file or +%line. It also has the nice property of not paying attention to +%unmodified lines; only lines that introduce new trailing whitespace +%cause problems. + +$B?^(B~\ref{ex:hook:ws.simple}$B$O(B\hook{pretxncommit}$B$H$$$&$V$i2<$,$j6uGr$r%A%'%C(B +$B%/$9$kC1=c$J%U%C%/$rF3F~$7$F$$$k!%$3$N%U%C%/$OC;$$$,!$$=$l$[$IM-MQ$G$O$J(B +$B$$!%99?7$,$V$i2<$,$j6uGr$r4^$`9T$r$I$N%U%!%$%k$KDI2C$7$F$b!$$3$N%U%C%/$O(B +$B%(%i!<%9%F!<%?%9$H6&$K=*N;$9$k$,!$LdBj$N$"$k%U%!%$%k$d9T$rFCDj$9$k$?$a$N(B +$B>pJs$O0l@ZI=<($7$J$$!%$3$N%U%C%/$OJQ99$N$J$$9T$K$OA4$/4X?4$r;}$?$J$$$H$$(B +$B$&NI$$@-<A$b;}$C$F$$$k!%?75,$K$V$i2<$,$j6uGr$r2C$($kLdBj$N$"$k9T$N$_$r8!(B +$B::$9$k!%(B \begin{figure}[ht] \interaction{hook.ws.better} - \caption{A better trailing whitespace hook} +% \caption{A better trailing whitespace hook} + \caption{$B$V$i2<$,$j6uGr$r%A%'%C%/$9$k%U%C%/$N2~NIHG(B} \label{ex:hook:ws.better} \end{figure} -The example of figure~\ref{ex:hook:ws.better} is much more complex, -but also more useful. It parses a unified diff to see if any lines -add trailing whitespace, and prints the name of the file and the line -number of each such occurrence. Even better, if the change adds -trailing whitespace, this hook saves the commit comment and prints the -name of the save file before exiting and telling Mercurial to roll the -transaction back, so you can use -\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the -saved commit message once you've corrected the problem. +%The example of figure~\ref{ex:hook:ws.better} is much more complex, +%but also more useful. It parses a unified diff to see if any lines +%add trailing whitespace, and prints the name of the file and the line +%number of each such occurrence. Even better, if the change adds +%trailing whitespace, this hook saves the commit comment and prints the +%name of the save file before exiting and telling Mercurial to roll the +%transaction back, so you can use +%\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}} to reuse the +%saved commit message once you've corrected the problem. -As a final aside, note in figure~\ref{ex:hook:ws.better} the use of -\command{perl}'s in-place editing feature to get rid of trailing -whitespace from a file. This is concise and useful enough that I will -reproduce it here. +$B?^(B~\ref{ex:hook:ws.better}$B$O$+$J$jJ#;($@$,!$$h$jM-MQ$G$"$k!%$3$N%U%C%/$OE}(B +$B9g7A<0$N(Bdiff$B$r%Q!<%9$7!$$V$i2<$,$j6uGr$r4^$`%i%$%s$rC5$9!%$=$7$F8+$D$1$k(B +$B$H%U%!%$%kL>$H9THV9f$rI=<($9$k!%$5$i$KJQ99$,$V$i2<$,$j6uGr$rDI2C$9$k$H!$(B +$B$3$N%U%C%/$O%3%_%C%H%3%a%s%H$rJ]B8$7!$=*N;A0$KJ]B8%U%!%$%k$NL>A0$rI=<($9(B +$B$k!%$=$7$F(BMercurial$B$K%H%i%s%6%/%7%g%s$r%m!<%k%P%C%/$9$k$3$H$r;X<($9$k!%Ld(B +$BBj$r=$@5$7$?8e$GJ]B8$5$l$?%3%_%C%H%a%C%;!<%8$r;H$&$K$O(B +\hgcmdargs{commit}{\hgopt{commit}{-l}~\emph{filename}}$B$H$9$l$P$h$$!%(B + +%As a final aside, note in figure~\ref{ex:hook:ws.better} the use of +%\command{perl}'s in-place editing feature to get rid of trailing +%whitespace from a file. This is concise and useful enough that I will +%reproduce it here. + +$B:G8e$K!$?^(B~\ref{ex:hook:ws.better}$B$N$h$&$K%U%!%$%k$+$i$V$i2<$,$j6uGr$r=|5n(B +$B$9$k$?$a$K(B\command{perl}$B%3%^%s%I$N%$%s%W%l%$%9JT=85!G=$rMQ$$$k!%$3$l$O$3(B +$B$3$G:F8=$9$k$KEv$?$C$F==J,C;$/$+$DM-8z$G$"$k!%(B + \begin{codesample2} perl -pi -e 's,\\s+\$,,' filename \end{codesample2} @@ -843,27 +923,43 @@ %\section{Bundled hooks} \section{$BAH$_9g$o$;%U%C%/(B} -Mercurial ships with several bundled hooks. You can find them in the -\dirname{hgext} directory of a Mercurial source tree. If you are -using a Mercurial binary package, the hooks will be located in the -\dirname{hgext} directory of wherever your package installer put -Mercurial. +%Mercurial ships with several bundled hooks. You can find them in the +%\dirname{hgext} directory of a Mercurial source tree. If you are +%using a Mercurial binary package, the hooks will be located in the +%\dirname{hgext} directory of wherever your package installer put +%Mercurial. + +Mercurial$B$K$O$$$/$D$+$N%U%C%/$,F1:-$5$l$F$$$k!%%U%C%/$O(BMercurial$B%=!<%9%D(B +$B%j!<$N(B\dirname{hgext}$B%G%#%l%/%H%j$K$"$k!%(B Mercurial$B$N%P%$%J%j%Q%C%1!<%8$r(B +$B;HMQ$7$F$$$k$N$G$"$l$P!$%U%C%/$O%Q%C%1!<%8%$%s%9%H!<%i$,(BMercurial$B$r%$%s%9(B +$B%H!<%k$7$?%G%#%l%/%H%jFb$N(B\dirname{hgext}$B%G%#%l%/%H%j$K$"$k$O$:$@!%(B %\subsection{\hgext{acl}---access control for parts of a repository} \subsection{\hgext{acl}---$B%j%]%8%H%j$NItJ,$KBP$9$k%"%/%;%9%3%s%H%m!<%k(B} -The \hgext{acl} extension lets you control which remote users are -allowed to push changesets to a networked server. You can protect any -portion of a repository (including the entire repo), so that a -specific remote user can push changes that do not affect the protected -portion. +%The \hgext{acl} extension lets you control which remote users are +%allowed to push changesets to a networked server. You can protect any +%portion of a repository (including the entire repo), so that a +%specific remote user can push changes that do not affect the protected +%portion. + +\hgext{acl}$B%(%/%9%F%s%7%g%s$O!$%j%b!<%H%f!<%6$K%A%'%s%8%;%C%H$r%M%C%H%o!<(B +$B%/@\B3$5$l$?%5!<%P$K%W%C%7%e$G$-$k$h$&$K$9$k!%FCDj$N%j%b!<%H%f!<%6$,J]8n(B +$B$5$l$?0J30$NItJ,$NJQ99$r%W%C%7%e$G$-$k$h$&$K%j%]%8%H%j$NG$0U$NItJ,!JA4BN(B +$B$r$b4^$`!K$rJ]8n$9$k$3$H$,$G$-$k!%(B -This extension implements access control based on the identity of the -user performing a push, \emph{not} on who committed the changesets -they're pushing. It makes sense to use this hook only if you have a -locked-down server environment that authenticates remote users, and -you want to be sure that only specific users are allowed to push -changes to that server. +%This extension implements access control based on the identity of the +%user performing a push, \emph{not} on who committed the changesets +%they're pushing. It makes sense to use this hook only if you have a +%locked-down server environment that authenticates remote users, and +%you want to be sure that only specific users are allowed to push +%changes to that server. + +$B$3$N%(%/%9%F%s%7%g%s$O%f!<%6$,%W%C%7%e$r9T$&:]$K!$C/$,%A%'%s%8%;%C%H$r%3(B +$B%_%C%H(B\emph{$B$G$-$J$$(B}$B$h$&$K$9$k$3$H$G%"%/%;%9%3%s%H%m!<%k$r<BAu$7$F$$$k!%(B +$B$3$N%U%C%/$O!$%j%b!<%H%f!<%6$NG'>Z$r9T$&J]8n$5$l$?%5!<%P4D6-$G!$;XDj$5$l(B +$B$?%f!<%6$@$1$,JQ99$r%5!<%P$K%W%C%7%e$G$-$k$h$&$K$7$?$$>l9g$K$N$_0UL#$r$J(B +$B$9!%(B %\subsubsection{Configuring the \hook{acl} hook} \subsubsection{\hook{acl}$B%U%C%/$N@_Dj(B} @@ -877,7 +973,7 @@ pretxnchangegroup.acl = python:hgext.acl.hook \end{codesample2} -The \hgext{acl} extension is configured using three sections. +The \hgext{acl} extension is configured using three sections. The \rcsection{acl} section has only one entry, \rcitem{acl}{sources}, which lists the sources of incoming changesets that the hook should @@ -944,7 +1040,7 @@ The \hgext{bugzilla} extension adds a comment to a Bugzilla bug whenever it finds a reference to that bug ID in a commit comment. You can install this hook on a shared server, so that any time a remote -user pushes changes to this server, the hook gets run. +user pushes changes to this server, the hook gets run. It adds a comment to the bug that looks like this (you can configure the contents of the comment---see below):