Fossil SCM
Hook documentation tweaks.
Commit
64184f934c8defa7de873e927540b1400d265f748a4938361b382f527df74537
Parent
f9fa692af911b66…
1 file changed
+40
-1
+40
-1
| --- www/hooks.md | ||
| +++ www/hooks.md | ||
| @@ -49,14 +49,20 @@ | ||
| 49 | 49 | |
| 50 | 50 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 51 | 51 | whenever new artifacts are received into the repository. The artifacts |
| 52 | 52 | have already been committed and so there is nothing that the |
| 53 | 53 | after-receive hook can do to block them. |
| 54 | + | |
| 55 | + * The after-receive hooks are intended to be run on a server to start | |
| 56 | + up a background testing or CI process. But they can also be run | |
| 57 | + on the client side. The key point is that after-receive hooks are | |
| 58 | + invoked by backoffice, so backoffice must be running in order to | |
| 59 | + fire after-receive hooks. | |
| 54 | 60 | |
| 55 | 61 | * The exit code from the after-receive script is ignored. |
| 56 | 62 | |
| 57 | - * The standard intput to the after-receive script is a list of | |
| 63 | + * The standard intput to the after-receive hook is a list of | |
| 58 | 64 | new artifacts, one per line. The first token on each line is the |
| 59 | 65 | hash of the new artifact. After the hash is a human-readable text |
| 60 | 66 | description of what the artifact represents. |
| 61 | 67 | |
| 62 | 68 | * Sometimes the same artifact can represent two or more things. |
| @@ -74,10 +80,23 @@ | ||
| 74 | 80 | database, then the database will need to be in WAL mode so that |
| 75 | 81 | readers can co-exist with the writer. Or the script might just |
| 76 | 82 | launch a background process that waits until the hook script finishes |
| 77 | 83 | and the transaction commits before it tries to access the repository |
| 78 | 84 | database. |
| 85 | + | |
| 86 | + * A push might not deliver all of the artifacts for a checkin. If | |
| 87 | + Fossil knows that a /xfer HTTP request is incomplete, it will defer | |
| 88 | + running the after-receive push for 60 seconds, or unti a complete | |
| 89 | + /xfer request is received. | |
| 90 | + | |
| 91 | + * The list of artifacts delivered to standard input of the | |
| 92 | + after-receive hook will not contain more than 24-hours worth | |
| 93 | + of artifacts. If the backoffice has been shut down for a while | |
| 94 | + such that after-receive hooks have not been running, and more | |
| 95 | + than 24-hours of changes have accumulated since the last run | |
| 96 | + of an after-receive hook, then only the most recent 24-hours | |
| 97 | + is included in the input. | |
| 79 | 98 | |
| 80 | 99 | ## Before-Commit Hooks |
| 81 | 100 | |
| 82 | 101 | * Before-commit hooks run during the "fossil commit" command before |
| 83 | 102 | the user is prompted for the check-in comment. Fossil holds |
| @@ -108,5 +127,25 @@ | ||
| 108 | 127 | |
| 109 | 128 | * Nothing is written to standard input of the before-commit hook. |
| 110 | 129 | The information transmitted to the before-commit hook is contained |
| 111 | 130 | in the "%A" auxiliary file. The before-commit hook must open and |
| 112 | 131 | read that file if it wants access to the commit information. |
| 132 | + | |
| 133 | +## Commit-Msg Hooks | |
| 134 | + | |
| 135 | + * Commit-msg hooks are not yet implemented. | |
| 136 | + | |
| 137 | + * The commit-msg hooks run during "fossil commit" after the check-in | |
| 138 | + messages has been entered by the user. The "%A" argument to the | |
| 139 | + commit-msg hook is the text of the commit message. The intent | |
| 140 | + of the commit-msg hook is to validate the text of the commit | |
| 141 | + message to (for example) check for typos or ensure that it | |
| 142 | + conforms to standards. | |
| 143 | + | |
| 144 | + * If any commit-msg hook returns a non-zero exit code, then | |
| 145 | + the commit is abandoned. All | |
| 146 | + commit-msg hooks must exit(0) in order for the commit to | |
| 147 | + proceed. | |
| 148 | + | |
| 149 | + * Commit-msg hooks are advisory only. Each developer is in total | |
| 150 | + control of the local repository and can easily bypass the hooks | |
| 151 | + to cause a non-conforming checkin to be committed. | |
| 113 | 152 |
| --- www/hooks.md | |
| +++ www/hooks.md | |
| @@ -49,14 +49,20 @@ | |
| 49 | |
| 50 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 51 | whenever new artifacts are received into the repository. The artifacts |
| 52 | have already been committed and so there is nothing that the |
| 53 | after-receive hook can do to block them. |
| 54 | |
| 55 | * The exit code from the after-receive script is ignored. |
| 56 | |
| 57 | * The standard intput to the after-receive script is a list of |
| 58 | new artifacts, one per line. The first token on each line is the |
| 59 | hash of the new artifact. After the hash is a human-readable text |
| 60 | description of what the artifact represents. |
| 61 | |
| 62 | * Sometimes the same artifact can represent two or more things. |
| @@ -74,10 +80,23 @@ | |
| 74 | database, then the database will need to be in WAL mode so that |
| 75 | readers can co-exist with the writer. Or the script might just |
| 76 | launch a background process that waits until the hook script finishes |
| 77 | and the transaction commits before it tries to access the repository |
| 78 | database. |
| 79 | |
| 80 | ## Before-Commit Hooks |
| 81 | |
| 82 | * Before-commit hooks run during the "fossil commit" command before |
| 83 | the user is prompted for the check-in comment. Fossil holds |
| @@ -108,5 +127,25 @@ | |
| 108 | |
| 109 | * Nothing is written to standard input of the before-commit hook. |
| 110 | The information transmitted to the before-commit hook is contained |
| 111 | in the "%A" auxiliary file. The before-commit hook must open and |
| 112 | read that file if it wants access to the commit information. |
| 113 |
| --- www/hooks.md | |
| +++ www/hooks.md | |
| @@ -49,14 +49,20 @@ | |
| 49 | |
| 50 | * The "after-receive" hook is run by [the backoffice](./backoffice.md) |
| 51 | whenever new artifacts are received into the repository. The artifacts |
| 52 | have already been committed and so there is nothing that the |
| 53 | after-receive hook can do to block them. |
| 54 | |
| 55 | * The after-receive hooks are intended to be run on a server to start |
| 56 | up a background testing or CI process. But they can also be run |
| 57 | on the client side. The key point is that after-receive hooks are |
| 58 | invoked by backoffice, so backoffice must be running in order to |
| 59 | fire after-receive hooks. |
| 60 | |
| 61 | * The exit code from the after-receive script is ignored. |
| 62 | |
| 63 | * The standard intput to the after-receive hook is a list of |
| 64 | new artifacts, one per line. The first token on each line is the |
| 65 | hash of the new artifact. After the hash is a human-readable text |
| 66 | description of what the artifact represents. |
| 67 | |
| 68 | * Sometimes the same artifact can represent two or more things. |
| @@ -74,10 +80,23 @@ | |
| 80 | database, then the database will need to be in WAL mode so that |
| 81 | readers can co-exist with the writer. Or the script might just |
| 82 | launch a background process that waits until the hook script finishes |
| 83 | and the transaction commits before it tries to access the repository |
| 84 | database. |
| 85 | |
| 86 | * A push might not deliver all of the artifacts for a checkin. If |
| 87 | Fossil knows that a /xfer HTTP request is incomplete, it will defer |
| 88 | running the after-receive push for 60 seconds, or unti a complete |
| 89 | /xfer request is received. |
| 90 | |
| 91 | * The list of artifacts delivered to standard input of the |
| 92 | after-receive hook will not contain more than 24-hours worth |
| 93 | of artifacts. If the backoffice has been shut down for a while |
| 94 | such that after-receive hooks have not been running, and more |
| 95 | than 24-hours of changes have accumulated since the last run |
| 96 | of an after-receive hook, then only the most recent 24-hours |
| 97 | is included in the input. |
| 98 | |
| 99 | ## Before-Commit Hooks |
| 100 | |
| 101 | * Before-commit hooks run during the "fossil commit" command before |
| 102 | the user is prompted for the check-in comment. Fossil holds |
| @@ -108,5 +127,25 @@ | |
| 127 | |
| 128 | * Nothing is written to standard input of the before-commit hook. |
| 129 | The information transmitted to the before-commit hook is contained |
| 130 | in the "%A" auxiliary file. The before-commit hook must open and |
| 131 | read that file if it wants access to the commit information. |
| 132 | |
| 133 | ## Commit-Msg Hooks |
| 134 | |
| 135 | * Commit-msg hooks are not yet implemented. |
| 136 | |
| 137 | * The commit-msg hooks run during "fossil commit" after the check-in |
| 138 | messages has been entered by the user. The "%A" argument to the |
| 139 | commit-msg hook is the text of the commit message. The intent |
| 140 | of the commit-msg hook is to validate the text of the commit |
| 141 | message to (for example) check for typos or ensure that it |
| 142 | conforms to standards. |
| 143 | |
| 144 | * If any commit-msg hook returns a non-zero exit code, then |
| 145 | the commit is abandoned. All |
| 146 | commit-msg hooks must exit(0) in order for the commit to |
| 147 | proceed. |
| 148 | |
| 149 | * Commit-msg hooks are advisory only. Each developer is in total |
| 150 | control of the local repository and can easily bypass the hooks |
| 151 | to cause a non-conforming checkin to be committed. |
| 152 |