Mercurial > hgbook
changeset 374:32c932f185ed
- fixed mq.tex a bit.
- started hook.tex.
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Fri, 19 Dec 2008 17:43:27 +0900 |
parents | 250ae1785828 |
children | 24c6081cea2b |
files | ja/hook.tex ja/mq.tex ja/todo.txt |
diffstat | 3 files changed, 125 insertions(+), 61 deletions(-) [+] |
line wrap: on
line diff
--- a/ja/hook.tex Wed Dec 17 20:17:55 2008 +0900 +++ b/ja/hook.tex Fri Dec 19 17:43:27 2008 +0900 @@ -1,4 +1,5 @@ -\chapter{Handling repository events with hooks} +%\chapter{Handling repository events with hooks} +\chapter{$B%j%]%8%H%j%$%Y%s%H$r%U%C%/$G<h$j07$&(B} \label{chap:hook} Mercurial offers a powerful mechanism to let you perform automated @@ -9,7 +10,8 @@ Hooks are called ``triggers'' in some revision control systems, but the two names refer to the same idea. -\section{An overview of hooks in Mercurial} +%\section{An overview of hooks in Mercurial} +\section{Mercurial$B$G$N%U%C%/$N35MW(B} Here is a brief list of the hooks that Mercurial supports. We will revisit each of these hooks in more detail later, in @@ -51,9 +53,11 @@ proceed. If the hook succeeds, the activity may proceed; if it fails, the activity is either not permitted or undone, depending on the hook. -\section{Hooks and security} +%\section{Hooks and security} +\section{$B%U%C%/$H%;%-%e%j%F%#(B} -\subsection{Hooks are run with your privileges} +%\subsection{Hooks are run with your privileges} +\subsection{$B%U%C%/$O%f!<%6$N8"8B$GF0:n$9$k(B} When you run a Mercurial command in a repository, and the command causes a hook to run, that hook runs on \emph{your} system, under @@ -86,7 +90,8 @@ \hgcmd{pull} or \hgcmd{incoming}), remember that it is the other repository's hooks you should be checking, not your own. -\subsection{Hooks do not propagate} +%\subsection{Hooks do not propagate} +\subsection{$B%U%C%/$OGH5Z$7$J$$(B} In Mercurial, hooks are not revision controlled, and do not propagate when you clone, or pull from, a repository. The reason for this is @@ -110,7 +115,8 @@ NFS filesystem, and use a site-wide \hgrc\ file to define hooks that all users will see. However, this too has its limits; see below. -\subsection{Hooks can be overridden} +%\subsection{Hooks can be overridden} +\subsection{$B%U%C%/$O%*!<%P%i%$%I2DG=$G$"$k(B} Mercurial allows you to override a hook definition by redefining the hook. You can disable it by setting its value to the empty string, or @@ -120,7 +126,8 @@ hooks, you should thus understand that your users can disable or override those hooks. -\subsection{Ensuring that critical hooks are run} +%\subsection{Ensuring that critical hooks are run} +\subsection{$B%/%j%F%#%+%k$J%U%C%/$,3N<B$K<B9T$5$l$k$h$&$K$9$k(B} Sometimes you may want to enforce a policy that you do not want others to be able to work around. For example, you may have a requirement @@ -148,7 +155,8 @@ ensure that all changes that people pull have been automatically vetted. -\section{Care with \texttt{pretxn} hooks in a shared-access repository} +%\section{Care with \texttt{pretxn} hooks in a shared-access repository} +\section{$B6&M-%"%/%;%9%j%]%8%H%j$G(B\texttt{pretxn}$B%U%C%/$r;H$&(B} If you want to use hooks to do some automated work in a repository that a number of people have shared access to, you need to be careful @@ -195,7 +203,8 @@ permanent, and should not be thought of as ``really there''. The longer the hook runs, the longer that window is open. -\subsection{The problem illustrated} +%\subsection{The problem illustrated} +\subsection{$BLdBj$N>\:Y(B} In principle, a good use for the \hook{pretxnchangegroup} hook would be to automatically build and test incoming changes before they are @@ -227,7 +236,8 @@ approach is that it does not impose a limit on the rate at which the repository can accept changes. -\section{A short tutorial on using hooks} +%\section{A short tutorial on using hooks} +\section{$B%U%C%/$N;HMQK!(B} \label{sec:hook:simple} It is easy to write a Mercurial hook. Let's start with a hook that @@ -247,7 +257,8 @@ hook. Mercurial passes extra information to the hook using environment variables (look for \envar{HG\_NODE} in the example). -\subsection{Performing multiple actions per event} +%\subsection{Performing multiple actions per event} +\subsection{1$B$D$N%$%Y%s%H$KJ#?t$N%"%/%7%g%s$r9T$&(B} Quite often, you will want to define more than one hook for a particular kind of event, as shown in example~\ref{ex:hook:ext}. @@ -277,7 +288,8 @@ you an immediate hint as to why the hook failed (see section~\ref{sec:hook:perm} for an example). -\subsection{Controlling whether an activity can proceed} +%\subsection{Controlling whether an activity can proceed} +\subsection{$BF0:n$,?J9T$G$-$k$+$I$&$+@)8f$9$k(B} \label{sec:hook:perm} In our earlier examples, we used the \hook{commit} hook, which is @@ -288,7 +300,7 @@ Mercurial defines a number of events that occur before an activity starts; or after it starts, but before it finishes. Hooks that trigger on these events have the added ability to choose whether the -activity can continue, or will abort. +activity can continue, or will abort. The \hook{pretxncommit} hook runs after a commit has all but completed. In other words, the metadata representing the changeset @@ -313,14 +325,16 @@ comment contains a bug ID. If it does, the commit can complete. If not, the commit is rolled back. -\section{Writing your own hooks} +%\section{Writing your own hooks} +\section{$B%*%j%8%J%k$N%U%C%/$r=q$/(B} When you are writing a hook, you might find it useful to run Mercurial either with the \hggopt{-v} option, or the \rcitem{ui}{verbose} config item set to ``true''. When you do so, Mercurial will print a message before it calls each hook. -\subsection{Choosing how your hook should run} +%\subsection{Choosing how your hook should run} +\subsection{$B%U%C%/$,$NF0:nJ}K!$rA*$V(B} \label{sec:hook:lang} You can write a hook either as a normal program---typically a shell @@ -344,7 +358,8 @@ performance (probably the majority of hooks), a shell script is perfectly fine. -\subsection{Hook parameters} +%\subsection{Hook parameters} +\subsection{$B%U%C%/%Q%i%a!<%?(B} \label{sec:hook:param} Mercurial calls each hook with a set of well-defined parameters. In @@ -361,7 +376,8 @@ named \texttt{foo}, while the environment variable for an external hook will be named \texttt{HG\_FOO}. -\subsection{Hook return values and activity control} +%\subsection{Hook return values and activity control} +\subsection{$B%U%C%/$NLa$jCM$HF0:n$N@)8f(B} A hook that executes successfully must exit with a status of zero if external, or return boolean ``false'' if in-process. Failure is @@ -372,7 +388,8 @@ For a hook that controls whether an activity can proceed, zero/false means ``allow'', while non-zero/true/exception means ``deny''. -\subsection{Writing an external hook} +%\subsection{Writing an external hook} +\subsection{$B30It%U%C%/$r:n@.$9$k(B} When you define an external hook in your \hgrc\ and the hook is run, its value is passed to your shell, which interprets it. This means @@ -392,7 +409,8 @@ being set to the values you have in your environment when testing the hook. -\subsection{Telling Mercurial to use an in-process hook} +%\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 @@ -413,7 +431,8 @@ \texttt{mymodule.submodule}, looks for the callable object named \texttt{myhook}, and calls it. -\subsection{Writing an in-process hook} +%\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: @@ -430,9 +449,11 @@ doesn't care about by dropping them into a keyword argument dict, as with \texttt{**kwargs} above. -\section{Some hook examples} +%\section{Some hook examples} +\section{$B%U%C%/$NNc(B} -\subsection{Writing meaningful commit messages} +%\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} @@ -445,7 +466,8 @@ \label{ex:hook:msglen.go} \end{figure} -\subsection{Checking for trailing whitespace} +%\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 @@ -512,7 +534,8 @@ perl -pi -e 's,\\s+\$,,' filename \end{codesample2} -\section{Bundled hooks} +%\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 @@ -520,7 +543,8 @@ \dirname{hgext} directory of wherever your package installer put Mercurial. -\subsection{\hgext{acl}---access control for parts of a repository} +%\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 @@ -535,7 +559,8 @@ you want to be sure that only specific users are allowed to push changes to that server. -\subsubsection{Configuring the \hook{acl} hook} +%\subsubsection{Configuring the \hook{acl} hook} +\subsubsection{\hook{acl}$B%U%C%/$N@_Dj(B} In order to manage incoming changesets, the \hgext{acl} hook must be used as a \hook{pretxnchangegroup} hook. This lets it see which files @@ -591,7 +616,8 @@ source/sensitive/** = intern \end{codesample2} -\subsubsection{Testing and troubleshooting} +%\subsubsection{Testing and troubleshooting} +\subsubsection{$B%F%9%H$HLdBj2r7h(B} If you want to test the \hgext{acl} hook, run it with Mercurial's debugging output enabled. Since you'll probably be running it on a @@ -606,7 +632,8 @@ to let you figure out why it is allowing or forbidding pushes from specific users. -\subsection{\hgext{bugzilla}---integration with Bugzilla} +%\subsection{\hgext{bugzilla}---integration with Bugzilla} +\subsection{\hgext{bugzilla}---Bugzilla$B$X$NE}9g(B} 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 @@ -644,7 +671,8 @@ ``requires testing''. \end{itemize} -\subsubsection{Configuring the \hook{bugzilla} hook} +%\subsubsection{Configuring the \hook{bugzilla} hook} +\subsubsection{\hook{bugzilla}$B%U%C%/$N@_Dj(B} \label{sec:hook:bugzilla:config} You should configure this hook in your server's \hgrc\ as an @@ -707,7 +735,8 @@ \texttt{processmail} on the server where Bugzilla is installed. \end{itemize} -\subsubsection{Mapping committer names to Bugzilla user names} +%\subsubsection{Mapping committer names to Bugzilla user names} +\subsubsection{$B%3%_%C%H<T$NL>A0$r(BBugzilla$B$N%f!<%6L>$X%^%C%W$9$k(B} By default, the \hgext{bugzilla} hook tries to use the email address of a changeset's committer as the Bugzilla user name with which to @@ -741,7 +770,8 @@ stephanie@example.com = steph \end{codesample2} -\subsubsection{Configuring the text that gets added to a bug} +%\subsubsection{Configuring the text that gets added to a bug} +\subsubsection{$B%P%0$KDI2C$5$l$?J8;zNs$r@_Dj$9$k(B} You can configure the text that this hook adds as a comment; you specify it in the form of a Mercurial template. Several \hgrc\ @@ -790,7 +820,8 @@ description:\\n\\t\{desc|tabindent\} \end{codesample2} -\subsubsection{Testing and troubleshooting} +%\subsubsection{Testing and troubleshooting} +\subsubsection{$B%F%9%H$HLdBj2r7h(B} The most common problems with configuring the \hgext{bugzilla} hook relate to running Bugzilla's \filename{processmail} script and mapping @@ -836,7 +867,8 @@ nor does it have an entry in your \rcsection{usermap} that maps it to a valid Bugzilla user name. -\subsection{\hgext{notify}---send email notifications} +%\subsection{\hgext{notify}---send email notifications} +\subsection{\hgext{notify}---$B%a!<%k$GDLCN$r9T$&(B} Although Mercurial's built-in web server provides RSS feeds of changes in every repository, many people prefer to receive change @@ -853,7 +885,8 @@ feature off entirely. It is useful for letting subscribers review changes immediately, rather than clicking to follow a URL. -\subsubsection{Configuring the \hgext{notify} hook} +%\subsubsection{Configuring the \hgext{notify} hook} +\subsubsection{\hgext{notify}$B%U%C%/$N@_Dj(B} You can set up the \hgext{notify} hook to send one email message per incoming changeset, or one per incoming group of changesets (all those @@ -948,17 +981,20 @@ [...snip...] \end{codesample2} -\subsubsection{Testing and troubleshooting} +%\subsubsection{Testing and troubleshooting} +\subsubsection{$B%F%9%H$HLdBj2r7h(B} Do not forget that by default, the \hgext{notify} extension \emph{will not send any mail} until you explicitly configure it to do so, by setting \rcitem{notify}{test} to \texttt{false}. Until you do that, it simply prints the message it \emph{would} send. -\section{Information for writers of hooks} +%\section{Information for writers of hooks} +\section{$B%U%C%/:n@=<T$X$N>pJs(B} \label{sec:hook:ref} -\subsection{In-process hook execution} +%\subsection{In-process hook execution} +\subsection{$B%W%m%;%9Fb%U%C%/$N<B9T(B} An in-process hook is called with arguments of the following form: \begin{codesample2} @@ -996,7 +1032,8 @@ convert a hash from hex to binary, use the \pymodfunc{mercurial.node}{bin} function. -\subsection{External hook execution} +%\subsection{External hook execution} +\subsection{$B%U%C%/$N30It<B9T(B} An external hook is passed to the shell of the user running Mercurial. Features of that shell, such as variable substitution and command @@ -1023,7 +1060,8 @@ succeeded. If it exits with a non-zero status, it is considered to have failed. -\subsection{Finding out where changesets come from} +%\subsection{Finding out where changesets come from} +\subsection{$B%A%'%s%8%;%C%H$N=P=h$rD4$Y$k(B} A hook that involves the transfer of changesets between a local repository and another may be able to find out information about the @@ -1031,7 +1069,8 @@ transferred, and in many cases \emph{where} they are being transferred to or from. -\subsubsection{Sources of changesets} +%\subsubsection{Sources of changesets} +\subsubsection{$B%A%'%s%8%;%C%H$N=P=h(B} \label{sec:hook:sources} Mercurial will tell a hook what means are, or were, used to transfer @@ -1050,7 +1089,8 @@ bundle. \end{itemize} -\subsubsection{Where changes are going---remote repository URLs} +%\subsubsection{Where changes are going---remote repository URLs} +\subsubsection{$BJQ99$N9T$-@h(B---$B%j%b!<%H%j%]%8%H%j$N(BURL} \label{sec:hook:url} When possible, Mercurial will tell a hook the location of the ``far @@ -1073,9 +1113,11 @@ client. \end{itemize} -\section{Hook reference} +%\section{Hook reference} +\section{$B%U%C%/;2>H(B} -\subsection{\hook{changegroup}---after remote changesets added} +%\subsection{\hook{changegroup}---after remote changesets added} +\subsection{\hook{changegroup}---$B%j%b!<%H%A%'%s%8%;%C%H$,DI2C$5$l$?8e(B} \label{sec:hook:changegroup} This hook is run after a group of pre-existing changesets has been @@ -1105,7 +1147,8 @@ \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) -\subsection{\hook{commit}---after a new changeset is created} +%\subsection{\hook{commit}---after a new changeset is created} +\subsection{\hook{commit}---$B?7$7$$%A%'%s%8%;%C%H$,:n@.$5$l$?8e(B} \label{sec:hook:commit} This hook is run after a new changeset has been created. @@ -1123,7 +1166,8 @@ See also: \hook{precommit} (section~\ref{sec:hook:precommit}), \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit}) -\subsection{\hook{incoming}---after one remote changeset is added} +%\subsection{\hook{incoming}---after one remote changeset is added} +\subsection{\hook{incoming}---$B%j%b!<%H%A%'%s%8%;%C%H$,DI2C$5$l$?8e(B} \label{sec:hook:incoming} This hook is run after a pre-existing changeset has been added to the @@ -1148,7 +1192,8 @@ See also: \hook{changegroup} (section~\ref{sec:hook:changegroup}) \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}), \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) -\subsection{\hook{outgoing}---after changesets are propagated} +%\subsection{\hook{outgoing}---after changesets are propagated} +\subsection{\hook{outgoing}---$B%A%'%s%8%;%C%H$,GH5Z$7$?8e(B} \label{sec:hook:outgoing} This hook is run after a group of changesets has been propagated out @@ -1175,7 +1220,10 @@ See also: \hook{preoutgoing} (section~\ref{sec:hook:preoutgoing}) -\subsection{\hook{prechangegroup}---before starting to add remote changesets} +%\subsection{\hook{prechangegroup}---before starting to add remote +%changesets} +\subsection{\hook{prechangegroup}---$B%j%b!<%H%A%'%s%8%;%C%H$,$,DI2C$5$l$k(B + $BA0(B} \label{sec:hook:prechangegroup} This controlling hook is run before Mercurial begins to add a group of @@ -1204,7 +1252,8 @@ \hook{incoming} (section~\ref{sec:hook:incoming}), , \hook{pretxnchangegroup} (section~\ref{sec:hook:pretxnchangegroup}) -\subsection{\hook{precommit}---before starting to commit a changeset} +%\subsection{\hook{precommit}---before starting to commit a changeset} +\subsection{\hook{precommit}---$B%A%'%s%8%;%C%H$r%3%_%C%H$9$kA0(B} \label{sec:hook:precommit} This hook is run before Mercurial begins to commit a new changeset. @@ -1230,7 +1279,9 @@ See also: \hook{commit} (section~\ref{sec:hook:commit}), \hook{pretxncommit} (section~\ref{sec:hook:pretxncommit}) -\subsection{\hook{preoutgoing}---before starting to propagate changesets} +%\subsection{\hook{preoutgoing}---before starting to propagate +%changesets} +\subsection{\hook{preoutgoing}---$B%A%'%s%8%;%C%H$rGH5Z$5$;$kA0$K(B} \label{sec:hook:preoutgoing} This hook is invoked before Mercurial knows the identities of the @@ -1253,7 +1304,8 @@ See also: \hook{outgoing} (section~\ref{sec:hook:outgoing}) -\subsection{\hook{pretag}---before tagging a changeset} +%\subsection{\hook{pretag}---before tagging a changeset} +\subsection{\hook{pretag}---$B%A%'%s%8%;%C%H$K%?%0$r$D$1$kA0$K(B} \label{sec:hook:pretag} This controlling hook is run before a tag is created. If the hook @@ -1275,8 +1327,10 @@ See also: \hook{tag} (section~\ref{sec:hook:tag}) -\subsection{\hook{pretxnchangegroup}---before completing addition of - remote changesets} +%\subsection{\hook{pretxnchangegroup}---before completing addition of +%remote changesets} +\subsection{\hook{pretxnchangegroup}---$B%j%b!<%H%A%'%s%8%;%C%H$NDI2C$r40(B + $BN;$9$kA0$K(B} \label{sec:hook:pretxnchangegroup} This controlling hook is run before a transaction---that manages the @@ -1315,7 +1369,10 @@ \hook{incoming} (section~\ref{sec:hook:incoming}), \hook{prechangegroup} (section~\ref{sec:hook:prechangegroup}) -\subsection{\hook{pretxncommit}---before completing commit of new changeset} +%\subsection{\hook{pretxncommit}---before completing commit of new +%changeset} +\subsection{\hook{pretxncommit}---$B?7$7$$%A%'%s%8%;%C%H$N%3%_%C%H$r40N;$9(B + $B$kA0$K(B} \label{sec:hook:pretxncommit} This controlling hook is run before a transaction---that manages a new @@ -1345,7 +1402,10 @@ See also: \hook{precommit} (section~\ref{sec:hook:precommit}) -\subsection{\hook{preupdate}---before updating or merging working directory} +%\subsection{\hook{preupdate}---before updating or merging working +%directory} +\subsection{\hook{preupdate}---$B%o!<%-%s%0%G%#%l%/%H%j$N%"%C%W%G!<%H$^$?(B + $B$O%^!<%8$NA0$K(B} \label{sec:hook:preupdate} This controlling hook is run before an update or merge of the working @@ -1366,7 +1426,8 @@ See also: \hook{update} (section~\ref{sec:hook:update}) -\subsection{\hook{tag}---after tagging a changeset} +%\subsection{\hook{tag}---after tagging a changeset} +\subsection{\hook{tag}---$B%A%'%s%8%;%C%H$K%?%0IU$1$7$?8e$K(B} \label{sec:hook:tag} This hook is run after a tag has been created. @@ -1386,7 +1447,10 @@ See also: \hook{pretag} (section~\ref{sec:hook:pretag}) -\subsection{\hook{update}---after updating or merging working directory} +%\subsection{\hook{update}---after updating or merging working +%directory} +\subsection{\hook{update}---$B%o!<%-%s%0%G%#%l%/%H%j$r99?7$^$?$O%^!<%8$7$?(B + $B8e$K(B} \label{sec:hook:update} This hook is run after an update or merge of the working directory @@ -1407,7 +1471,7 @@ See also: \hook{preupdate} (section~\ref{sec:hook:preupdate}) -%%% Local Variables: +%%% Local Variables: %%% mode: yatex %%% TeX-master: "00book" -%%% End: +%%% End:
--- a/ja/mq.tex Wed Dec 17 20:17:55 2008 +0900 +++ b/ja/mq.tex Fri Dec 19 17:43:27 2008 +0900 @@ -496,7 +496,7 @@ Mercurial$B%3%^%s%I$,A4$/F1$8$h$&$K;H$($k!%(B %\subsection{Refreshing a patch} -\subsection{$B%Q%C%A$N:F@8(B} +\subsection{$B%Q%C%A$N%j%U%l%C%7%e(B} %When you reach a point where you want to save your work, use the %\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
--- a/ja/todo.txt Wed Dec 17 20:17:55 2008 +0900 +++ b/ja/todo.txt Fri Dec 19 17:43:27 2008 +0900 @@ -1,13 +1,13 @@ translate proofread 00book.tex 100% branch.tex 100% -collab.tex 70% +collab.tex 100% concepts.tex daily.tex 2% filenames.tex 100% hg_id.tex noneed hgext.tex 100% -hook.tex +hook.tex 1% intro.tex license.tex mq-collab.tex 100%