Add some magic to find the man page on dim help, and display the man page like before. Add make target to create dim.html version of the man page. --- Makefile | 9 +- dim | 324 +++------------------------------------------------------------ dim.rst | 309 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 327 insertions(+), 315 deletions(-) create mode 100644 dim.rst diff --git a/Makefile b/Makefile index d95519a00f16..7c18885e24fa 100644 --- a/Makefile +++ b/Makefile @@ -4,17 +4,22 @@ # the wavedrom json, copy-pasting to and from http://wavedrom.com/editor.html is # handy as it shows the result live. -all: drm-intel.html +all: drm-intel.html dim.html %.svg: %.dot dot -T svg -o $@ $< +%.html: %.rst + rst2html $< > $@ + # the sed bit here is a hack to make wavedrom process the timeline drm-intel.html: drm-intel.rst drm-intel-flow.svg drm-intel-timeline.rst drm-intel-timeline.json rst2html $< > $@ sed -i 's/<body/<body onload="WaveDrom.ProcessAll()"/' $@ +dim.html: dim.rst + clean: - rm -f drm-intel.html drm-intel-flow.svg + rm -f drm-intel.html drm-intel-flow.svg dim.html .PHONY: all clean diff --git a/dim b/dim index 4b08291e487d..03e2709159d5 100755 --- a/dim +++ b/dim @@ -964,7 +964,16 @@ case "$subcommand" in rm drivers/gpu/drm/i915/*.ko &> /dev/null || true make C=1 drivers/gpu/drm/i915/i915.ko ;; - *) + help|*) + manpage=$DIM_PREFIX/maintainer-tools/dim.rst + if [ ! -e "$manpage" ]; then + manpage=$(dirname $(readlink -f $0))/dim.rst + if [ ! -e "$manpage" ]; then + echo "Can't find the man page. See http://cgit.freedesktop.org/drm-intel/tree/dim.rst?h=maintainer-tools"; + exit 1 + fi + fi + if hash rst2man 2>/dev/null; then renderer=rst2man pager="man -l -" @@ -972,318 +981,7 @@ case "$subcommand" in renderer=cat pager=${PAGER:-cat} fi - $renderer <<HERE | $pager -===== - dim -===== - ---------------------------- -drm-intel maintainer script ---------------------------- - -:Author: Daniel Vetter <daniel.vetter@xxxxxxxx> -:Author: Jani Nikula <jani.nikula@xxxxxxxxx> -:Date: 2014-05-15 -:Copyright: 2012-2015 Intel Corporation -:Manual section: 1 -:Manual group: maintainer tools - -SYNOPSIS -======== - -**dim** [*option* ...] *command* - -DESCRIPTION -=========== - -drm-intel maintainer script. - -Branch Model ------------- - -The dim flow has 3 main development branches: - -- drm-intel-next-queued for feature work. This branch gets regularly pushed to - drm-intel-next and tagged and then sent on to the upstream drm-next branch - using *update-next*. The cut-off for the last pull request to drm-next is - around -rc5. After that point patches in drm-intel-next-queued already aim at - the next but one and not the next merge window. - -- drm-intel-next-fixes is to collect fixes for the current merge window after - the -rc5 feature cut-off in drm-next. - -- drm-intel-fixes is for fixes for the current -rc1 kernel. This is separate - from drm-intel-next-fixes since the merge window feature cutoff at -rc5 is a - few weeks ahead of the final release of the previous kernel. - - There's separate tracking branches for inclusion into linux-next to make sure - that the feature work in drm-intel-next-queued aimed for the next but one - merge window doesn't cause unecassary conflicts in linux-next - in that case - only drm-intel-next-fixes is included in linux-next. The switchover happens - when drm-intel-fixes has caught up (in git terms: drm-intel-next-fixes is - direct ancestor of drm-intel-fixes). Therefore only roll drm-intel-fixes - forward once -rc1 is released - -In addition there's 2 permanent topic branches: - -- topic/drm-misc carries core drm patches aimed at the next merge window. - -- topic/drm-fixes carries core drm fixes for the current -rc kernels. - -Additional topic branches are created as needed using *create-branch* and -*remove-branch*. - -OPTIONS -======= - --f Ignore some error conditions. --d Dry run. --i Interactive mode. - -COMMANDS -======== - -setup *prefix* --------------- -Setup git maintainer branches in the given prefix. - -nightly-forget --------------- -Forget git rerere solutions for nightly merges in case they -contain a bogus merge resolution. - -update-branches ---------------- -Updates all maintainer branches. Only needs to be run to synchronize branches -between different machines (or maintainers fwiw). As long a given branch is -always maintained from the same machine, even if different branches are -maintained on different machines (by different maintainers), there's no need to -run this command. - -rebuild-nightly ---------------- -Rebuilds the nightly branch. Useful when ad-hoc trees are -included in -nightly. - -cat-to-fixup ------------- - -Pipes stdin into the fixup patch file for the current -nightly merge. - -push-branch branch [*git push arguments*] ------------------------------------------ - -push-fixes|pf [*git push arguments*] ------------------------------------- - -push-next-fixes|pnf [*git push arguments*] ------------------------------------------- - -push-queued|pq [*git push arguments*] -------------------------------------- - -Updates the named branch, or drm-intel-fixes, drm-intel-next-fixes or the -drm-intel-next-queued branch respectively. Complains if that's not the current -branch, assuming that patches got merged to the wrong branch. After pushing also -updates linux-next and drm-intel-nightly branches. - -checkout *branch* ------------------ -Checks out the named branch. - -co --- - -cof ---- - -conf ----- -Checks out the drm-intel-fixes branch, dinf or dinq respectively for merging -patches. - -apply-branch|ab|sob branch [*git am arguments*] ------------------------------------------------ -Applys a patch to the given branch, complaining if it is not -checked out yet. - -apply-fixes|af [*git am arguments*] ------------------------------------ - -apply-next-fixes|anf [*git am arguments*] ------------------------------------------ - -apply-queued|aq [*git am arguments*] ------------------------------------- -Applies a patch to -fixes, -next-fixes or -next-queued respectively, complains -if it's not the right branch. Additional arguments are passed to git am. - -magic-patch|mp [-a] -------------------- -Apply a patch using patch and then wiggle in any conflicts. When passing the -option -a automatically changes the working directory into the git repository -used by the last previous branch-specific command. This is useful with the -per-branch workdir model. - -magic-rebase-resolve|mrr ------------------------- -Tries to resolve a rebase conflict by first resetting the tree -and the using the magic patch tool. Then builds the tree, adds -any changes with git add -u and continues the rebase. - -cd --- -Changes the working directory into the git repository used by the last previous -branch-specific command. This is implemented as a bash-function to make it -useful in interactive shells and scripts. Only available when the bash -completion is sourced. - -apply-resolved|ar ------------------ -Compile-test the current tree and if successfully resolve a -confilicted git am. Also runs the patch checker afterwards. - -apply-igt|ai ------------- -Apply a patch to the i-g-t repository. - -tc *commit-ish* ---------------- -Prints the linux kernel tag which contains the supplied commit-ish - -check-patch|cp [*commit-ish* [.. *commit-ish*]] ------------------------------------------------ -Runs the given commit range commit-ish..commit-ish through the check tools. If -no commit-ish is passed, defaults to HEAD^..HEAD. If one commit-ish is passed -instead of a range, the range commit-ish..HEAD is used. - -cherry-pick *commit-ish* [*git cherry-pick arguments*] ------------------------------------------------------- - -Improved git cherry-pick version which also scans drm-intel-nightly for any -mentions of the cherry-picked commit. Should be used when cherry-pick from -next -to -fixes to make sure all fixups are picked, too. In dry-run mode/-d only the -patch list is generated. - -pull-request *branch* *upstream* --------------------------------- -Fetch the *upstream* remote to make sure it's up-to-date, create and push a date -based tag for the *branch*, generate a pull request template with the specified -*upstream*, and finally start \$DIM_MUA with the template with subject and -recipients already set. - -Since the tag for the *branch* is date based, the pull request can be -regenerated with the same commands if something goes wrong. - -pull-request-fixes [*upstream*] -------------------------------- -This is a special case of **pull-request**, with *drm-intel-fixes* as the -branch and *origin/master* as the default upstream. - -pull-request-next-fixes [*upstream*] ------------------------------------- -This is a special case of **pull-request**, with *drm-intel-next-fixes* as -the branch and *\$DRM_UPSTREAM/drm-next* as the default upstream. - -pull-request-next [*upstream*] ------------------------------- -This is similar to **pull-request**, but for feature pull requests, with -*drm-intel-next* as the branch and *\$DRM_UPSTREAM/drm-next* as the default -upstream. - -The difference to **pull-request** is that this command does not generate a -tag; this must have been done previously using **update-next**. This also means -that the pull request can be regenerated with the same commands if something -goes wrong. - -update-next ------------ -Pushes out the latest dinq to drm-intel-next and tags it. Also -pushes out the latest nightly to drm-intel-testing. For an -overview a gitk view of the currently unmerged feature pile is -opened. - -Also checks that the drm-intel-fixes|-next-queued are fully -merged into -nightly to avoid operator error. - -tag-next --------- - -Pushes a new tag for the current drm-intel-next state after checking that the -remote is up-to-date. Useful if drm-intel-next has been changed since the last -run of the update-next command (e.g. to apply a hotfix before sending out the -pull request). - -checker -------- -Run sparse on the kernel. - -create-branch *branch* [*commit-ish*] -------------------------------------- - -Create a new topic branch with the given name. Note that topic/ is not -automatically prepended. The branch starts at HEAD or the given commit-ish. - -remove-branch *branch* ----------------------- - -Remove the given topic branch. - -create-workdir (*branch* | all) -------------------------------- - -Create a separate workdir for the branch with the given name (requires that -git-new-workdir from git-core contrib is installed), or for all branches if -"all" is given. - -for-each-workdir|fw *command* ------------------------------ - -Run the given command in all active workdirs including the main repository under -\$DIM_DRM_INTEL. - -help ----- -Show this help. Install **rst2man(1)** for best results. - -ENVIRONMENT -=========== - -DIM_CONFIG ----------- -Path to the dim configuration file, \$HOME/.dimrc by default, which is sourced -if it exists. It can be used to set other environment variables to control dim. - -DIM_PREFIX ----------- -Path prefix for kernel repositories. - -DIM_DRM_INTEL -------------- -The main maintainer repository under \$DIM_PREFIX. - -DIM_DRM_INTEL_REMOTE --------------------- -Name of the $drm_intel_ssh remote within \$DIM_DRM_INTEL. - -DIM_DRM_UPSTREAM_REMOTE ------------------------ -Name of the $drm_upstream_git remote within \$DIM_DRM_INTEL. - -DIM_MUA -------- -Mail user agent. Must support the following subset of **mutt(1)** command line -options: \$DIM_MUA [-s subject] [-i file] [-c cc-addr] to-addr [...] - -DIM_TEMPLATE_HELLO ------------------- -Path to a file containing a greeting template for pull request mails. - -DIM_TEMPLATE_SIGNATURE ----------------------- -Path to a file containing a signature template for pull request mails. -HERE - exit 0 + $renderer < $manpage | $pager ;; esac diff --git a/dim.rst b/dim.rst new file mode 100644 index 000000000000..da5fdd3a814d --- /dev/null +++ b/dim.rst @@ -0,0 +1,309 @@ +===== + dim +===== + +--------------------------- +drm-intel maintainer script +--------------------------- + +:Author: Daniel Vetter <daniel.vetter@xxxxxxxx> +:Author: Jani Nikula <jani.nikula@xxxxxxxxx> +:Date: 2014-05-15 +:Copyright: 2012-2015 Intel Corporation +:Manual section: 1 +:Manual group: maintainer tools + +SYNOPSIS +======== + +**dim** [*option* ...] *command* + +DESCRIPTION +=========== + +drm-intel maintainer script. + +Branch Model +------------ + +The dim flow has 3 main development branches: + +- drm-intel-next-queued for feature work. This branch gets regularly pushed to + drm-intel-next and tagged and then sent on to the upstream drm-next branch + using *update-next*. The cut-off for the last pull request to drm-next is + around -rc5. After that point patches in drm-intel-next-queued already aim at + the next but one and not the next merge window. + +- drm-intel-next-fixes is to collect fixes for the current merge window after + the -rc5 feature cut-off in drm-next. + +- drm-intel-fixes is for fixes for the current -rc1 kernel. This is separate + from drm-intel-next-fixes since the merge window feature cutoff at -rc5 is a + few weeks ahead of the final release of the previous kernel. + + There's separate tracking branches for inclusion into linux-next to make sure + that the feature work in drm-intel-next-queued aimed for the next but one + merge window doesn't cause unecassary conflicts in linux-next - in that case + only drm-intel-next-fixes is included in linux-next. The switchover happens + when drm-intel-fixes has caught up (in git terms: drm-intel-next-fixes is + direct ancestor of drm-intel-fixes). Therefore only roll drm-intel-fixes + forward once -rc1 is released + +In addition there's 2 permanent topic branches: + +- topic/drm-misc carries core drm patches aimed at the next merge window. + +- topic/drm-fixes carries core drm fixes for the current -rc kernels. + +Additional topic branches are created as needed using *create-branch* and +*remove-branch*. + +OPTIONS +======= + +-f Ignore some error conditions. +-d Dry run. +-i Interactive mode. + +COMMANDS +======== + +setup *prefix* +-------------- +Setup git maintainer branches in the given prefix. + +nightly-forget +-------------- +Forget git rerere solutions for nightly merges in case they +contain a bogus merge resolution. + +update-branches +--------------- +Updates all maintainer branches. Only needs to be run to synchronize branches +between different machines (or maintainers fwiw). As long a given branch is +always maintained from the same machine, even if different branches are +maintained on different machines (by different maintainers), there's no need to +run this command. + +rebuild-nightly +--------------- +Rebuilds the nightly branch. Useful when ad-hoc trees are +included in -nightly. + +cat-to-fixup +------------ + +Pipes stdin into the fixup patch file for the current -nightly merge. + +push-branch branch [*git push arguments*] +----------------------------------------- + +push-fixes|pf [*git push arguments*] +------------------------------------ + +push-next-fixes|pnf [*git push arguments*] +------------------------------------------ + +push-queued|pq [*git push arguments*] +------------------------------------- + +Updates the named branch, or drm-intel-fixes, drm-intel-next-fixes or the +drm-intel-next-queued branch respectively. Complains if that's not the current +branch, assuming that patches got merged to the wrong branch. After pushing also +updates linux-next and drm-intel-nightly branches. + +checkout *branch* +----------------- +Checks out the named branch. + +co +-- + +cof +--- + +conf +---- +Checks out the drm-intel-fixes branch, dinf or dinq respectively for merging +patches. + +apply-branch|ab|sob branch [*git am arguments*] +----------------------------------------------- +Applys a patch to the given branch, complaining if it is not +checked out yet. + +apply-fixes|af [*git am arguments*] +----------------------------------- + +apply-next-fixes|anf [*git am arguments*] +----------------------------------------- + +apply-queued|aq [*git am arguments*] +------------------------------------ +Applies a patch to -fixes, -next-fixes or -next-queued respectively, complains +if it's not the right branch. Additional arguments are passed to git am. + +magic-patch|mp [-a] +------------------- +Apply a patch using patch and then wiggle in any conflicts. When passing the +option -a automatically changes the working directory into the git repository +used by the last previous branch-specific command. This is useful with the +per-branch workdir model. + +magic-rebase-resolve|mrr +------------------------ +Tries to resolve a rebase conflict by first resetting the tree +and the using the magic patch tool. Then builds the tree, adds +any changes with git add -u and continues the rebase. + +cd +-- +Changes the working directory into the git repository used by the last previous +branch-specific command. This is implemented as a bash-function to make it +useful in interactive shells and scripts. Only available when the bash +completion is sourced. + +apply-resolved|ar +----------------- +Compile-test the current tree and if successfully resolve a +confilicted git am. Also runs the patch checker afterwards. + +apply-igt|ai +------------ +Apply a patch to the i-g-t repository. + +tc *commit-ish* +--------------- +Prints the linux kernel tag which contains the supplied commit-ish + +check-patch|cp [*commit-ish* [.. *commit-ish*]] +----------------------------------------------- +Runs the given commit range commit-ish..commit-ish through the check tools. If +no commit-ish is passed, defaults to HEAD^..HEAD. If one commit-ish is passed +instead of a range, the range commit-ish..HEAD is used. + +cherry-pick *commit-ish* [*git cherry-pick arguments*] +------------------------------------------------------ + +Improved git cherry-pick version which also scans drm-intel-nightly for any +mentions of the cherry-picked commit. Should be used when cherry-pick from -next +to -fixes to make sure all fixups are picked, too. In dry-run mode/-d only the +patch list is generated. + +pull-request *branch* *upstream* +-------------------------------- +Fetch the *upstream* remote to make sure it's up-to-date, create and push a date +based tag for the *branch*, generate a pull request template with the specified +*upstream*, and finally start \$DIM_MUA with the template with subject and +recipients already set. + +Since the tag for the *branch* is date based, the pull request can be +regenerated with the same commands if something goes wrong. + +pull-request-fixes [*upstream*] +------------------------------- +This is a special case of **pull-request**, with *drm-intel-fixes* as the +branch and *origin/master* as the default upstream. + +pull-request-next-fixes [*upstream*] +------------------------------------ +This is a special case of **pull-request**, with *drm-intel-next-fixes* as +the branch and *\$DRM_UPSTREAM/drm-next* as the default upstream. + +pull-request-next [*upstream*] +------------------------------ +This is similar to **pull-request**, but for feature pull requests, with +*drm-intel-next* as the branch and *\$DRM_UPSTREAM/drm-next* as the default +upstream. + +The difference to **pull-request** is that this command does not generate a +tag; this must have been done previously using **update-next**. This also means +that the pull request can be regenerated with the same commands if something +goes wrong. + +update-next +----------- +Pushes out the latest dinq to drm-intel-next and tags it. Also +pushes out the latest nightly to drm-intel-testing. For an +overview a gitk view of the currently unmerged feature pile is +opened. + +Also checks that the drm-intel-fixes|-next-queued are fully +merged into -nightly to avoid operator error. + +tag-next +-------- + +Pushes a new tag for the current drm-intel-next state after checking that the +remote is up-to-date. Useful if drm-intel-next has been changed since the last +run of the update-next command (e.g. to apply a hotfix before sending out the +pull request). + +checker +------- +Run sparse on the kernel. + +create-branch *branch* [*commit-ish*] +------------------------------------- + +Create a new topic branch with the given name. Note that topic/ is not +automatically prepended. The branch starts at HEAD or the given commit-ish. + +remove-branch *branch* +---------------------- + +Remove the given topic branch. + +create-workdir (*branch* | all) +------------------------------- + +Create a separate workdir for the branch with the given name (requires that +git-new-workdir from git-core contrib is installed), or for all branches if +"all" is given. + +for-each-workdir|fw *command* +----------------------------- + +Run the given command in all active workdirs including the main repository under +\$DIM_DRM_INTEL. + +help +---- +Show this help. Install **rst2man(1)** for best results. + +ENVIRONMENT +=========== + +DIM_CONFIG +---------- +Path to the dim configuration file, \$HOME/.dimrc by default, which is sourced +if it exists. It can be used to set other environment variables to control dim. + +DIM_PREFIX +---------- +Path prefix for kernel repositories. + +DIM_DRM_INTEL +------------- +The main maintainer repository under \$DIM_PREFIX. + +DIM_DRM_INTEL_REMOTE +-------------------- +Name of the $drm_intel_ssh remote within \$DIM_DRM_INTEL. + +DIM_DRM_UPSTREAM_REMOTE +----------------------- +Name of the $drm_upstream_git remote within \$DIM_DRM_INTEL. + +DIM_MUA +------- +Mail user agent. Must support the following subset of **mutt(1)** command line +options: \$DIM_MUA [-s subject] [-i file] [-c cc-addr] to-addr [...] + +DIM_TEMPLATE_HELLO +------------------ +Path to a file containing a greeting template for pull request mails. + +DIM_TEMPLATE_SIGNATURE +---------------------- +Path to a file containing a signature template for pull request mails. -- 2.1.4 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
