From 7063e9b807680aa0d19ff88cef8d4232eff0a776 Mon Sep 17 00:00:00 2001 From: Frantisek Hrbata Date: Tue, 22 Dec 2020 10:07:39 +0100 Subject: [PATCH] doc: add doc about configuration and update refs info Signed-off-by: Frantisek Hrbata --- Documentation/git-mr.txt | 340 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 290 insertions(+), 50 deletions(-) diff --git a/Documentation/git-mr.txt b/Documentation/git-mr.txt index 4a0236d..6b6270f 100644 --- a/Documentation/git-mr.txt +++ b/Documentation/git-mr.txt @@ -15,59 +15,299 @@ SYNOPSIS DESCRIPTION ----------- -'GIMRR' is abbreviation for **G**it **I**ntegrated **M**erge **R**equest **R**eview. -It's goal is to provide a simple, but effective approach how to manage and review -MRs in git. All data related to MRs are stored within git and 'git-mr' is just a -set of Python scripts to make this data available to users in some reasonable form. -This allows 'git-mr' to leverage git's transport protocol, distributed approach and -possibility to work offline. - -Once a MR is created by link:git-mr-create.html[git-mr-create(1)], you can -attach arbitrary tags to it or it's commits with link:git-mr-tag.html[git-mr-tag(1)] -and present them in a customizable format with -link:git-mr-show.html[git-mr-show(1)]. Review of MR can be done within your -favorite MUA, because 'git-mr' can generate mboxes with -link:git-mr-mbox.html[git-mr-mbox(1)] and link:git-mr-sendmail.html[git-mr-sendmail(1)] -can be used for mail delivery, which in context of 'git-mr' is creating a new -user's mbox entry. This should provide environment similar to email based -distribution of patches and their review. Since 'git-mr' just presents data -stored in git, other approaches and review methods can be implemented. - -All data are tracked within 'refs/mrs' refs namespace, where MRs are stored. MR is -identified by full SHA-1, which is a tip of a branch from which the MR was created. -This SHA-1 is also an unique identifier of the MR, which has several advantages. -You can pass MR to 'git-checkout' and use it as normal branch. Once on that branch -you don't need to specify MR for 'git-mr' commands, because by default they use -HEAD as a MR identifier. Each user has it's own refs namespace for each MR under -specified username. This allows to enforce a push policy easily, because each user -is allowed to push only his namespace. - -The full 'git-mr' ref format is 'refs/mrs///{head,tags,mbox}', where -'' is MR's SHA-1 identifier, is username as registered on server -and '{head,tags,mbox}' are three ref types used by 'git-mr', which are described -in *REF TYPES* section. +'GIMRR' is an abbreviation for **G**it **I**ntegrated **M**erge **R**equest +**R**eview. It's goal is to provide a simple, but effective approach how to +manage and review MRs within git. All data related to MRs are stored within git +and 'git-mr' is just a set of Python scripts to make this data available to +users in some reasonable form. This allows 'git-mr' to leverage git's transport +protocol, distributed approach and possibility to work offline. Since gimrr is +based around data stored in git, it's easy to extend its functionality +and to customize it. It also doesn't force any particular workflow for MR +review and it's up to each project to set its rules for MR acceptance. +For this purpose 'git-mr' provides general tags, which can be managed +with link:git-mr-tag.html[git-mr-tag(1)]. + +Once a MR is created with link:git-mr-create.html[git-mr-create(1)], you can +attach arbitrary tags to it or its commits with +link:git-mr-tag.html[git-mr-tag(1)] and present them in a customizable format +with link:git-mr-show.html[git-mr-show(1)]. + +Review of MR can be done purely from command line with +link:git-mr-comment-list.html[git-mr-comment-list(1)], +link:git-mr-comment-show.html[git-mr-comment-show(1)] and +link:git-mr-reply.html[git-mr-reply(1)]. These three commands provide the +basic interface for MR review without a need for any external programs. + +Other possibility how to review MR is within your favorite MUA, because +'git-mr' can generate mboxes with link:git-mr-mbox.html[git-mr-mbox(1)] and +link:git-mr-sendmail.html[git-mr-sendmail(1)] can be used for mail delivery, +which in context of 'git-mr' is creating a new user's mbox entry. This should +provide environment similar to the email based distribution of patches and their +review, except that git protocol is used instead of SMTP. Note that +link:git-mr-mbox.html[git-mr-mbox(1)] can incrementally append new MRs and +comments to a single mbox. In combination with +link:git-mr-fetch.html[git-mr-fetch(1)] and +link:git-mr-push.html[git-mr-push(1)], used for MRs and comments +synchronization, this can be configured to provide the same environment as doing +reviews on mailing list. Since 'git-mr' just presents data stored in git, other +approaches and review methods can be implemented. + +All data are tracked within 'refs/mrs' refs namespace, where MRs are stored. MR +is identified by full SHA-1, which is a tip of a branch from which the MR was +created. This SHA-1 is also an unique identifier of the MR, which has several +advantages. You can pass MR to 'git-checkout' and use it as normal branch. Once +on that branch you don't need to specify MR for 'git-mr' commands, because by +default they use HEAD as a MR identifier. Each user has it's own refs namespace +for each MR under specified username. This allows to enforce a push policy +easily, because each user is allowed to push to his namespace only. Please see +link:git-mr-update.html[git-mr-update(1)] for info about default push policy. + +The full 'git-mr' ref format is +'refs/mrs///{head,mr,tags,mbox}', where +'' is MR's SHA-1 identifier, is user name as registered on +server and '{head,mr,tags,mbox}' are four ref types used by 'git-mr', which are +described in *REF TYPES* section. + + +QUICK TRYOUT +------------ +If you want to quickly check gimrr's functionality, just install gimrr and +use any of your existing git repo. There is no need to set up server or install +anything else. Of course link:git-mr-fetch.html[git-mr-fetch(1)] and +link:git-mr-push.html[git-mr-push(1)] will not work as expected, but you will +be able to use all other gimrr's commands properly. + +* *add gimrr user* ++ +Inside of any existing git repo add gimrr user. For this quick tryout you can +pick by yourself. ++ +---- +$ git config mr.user +---- + +Now you should be able to start e.g. with +link:git-mr-create.html[git-mr-create(1)]. + + +SERVER SETUP +------------ +Gimrr requires sshd and gimrr user account, which will be used by gimrr users. +The access is controlled via 'authorized_keys', where each gimrr user's public +key is associated with 'GIMRR_USER' environment variable. 'GIMRR_USER' contains +user name and it is used by link:git-mr-update.html[git-mr-update(1)] to +distinguish gimrr users and to enforce push policy. All gimrr users should +be using restricted 'git-shell'. Here follows basic configuration. + +* *sshd configuration* + +** Edit '/etc/ssh/sshd_config' and allow sshd to process *environment=* options +in 'authorized_keys' by adding ++ +---- +PermitUserEnvironment "GIMRR_*" +---- + +** Reload sshd configuration ++ +---- +# systemctl reload sshd +---- + +* *user account configuration* + +** Add gimrr user account ++ +---- +# useradd gimrr +# passwd gimrr +---- + +** Create authorized_keys file ++ +---- +# su - gimrr +$ mkdir ~/.ssh +$ chmod 700 ~/.ssh +$ touch ~/.ssh/authorized_keys +$ chmod 600 ~/.ssh/authorized_keys +---- + +* *git repo configuration* + +** Create bare git repo for my_project ++ +---- +$ git init --bare my_project +---- + +** Set gimrr's link:git-mr-update.html[git-mr-update(1)] hook ++ +---- +$ ln -sf /usr/bin/git-mr-update my_project/hooks/update +---- + +** Add gimrr user 'admin' as maintainer for my_project. This user will have full + access to the repo. ++ +---- +$ git -C my_project config mr.admins admin +---- + +* *add gimrr users* + +** Add gimrr user public key to 'authorized_keys'. Here public key for admin is + added. Other gimrr users can be added in the same way. Please make sure each + public key has a proper 'GIMRR_USER' set. ++ +---- +environment="GIMRR_USER=admin",restrict,command="/usr/bin/git-shell -c \"$SSH_ORIGINAL_COMMAND\"" +---- + + +CLIENT SETUP +------------ +* *generate ssh keys* ++ +User should generate ssh keys and send the public key(e.g. gimrr.pub) +to the server administrator. ++ +---- +ssh-keygen -t rsa -C "gimrr" -f ~/.ssh/gimrr +---- ++ +Once the public key is added on the server side, you will need to know which +gimrr user is associated with it, so you can set it in your cloned repo +configuration. + +* *clone repo* ++ +Note that gimrr user account is used in the URL for clone. This account is +same for all gimrr users, who are distinguished based on the public keys +and 'GIMRR_USER' environment variable in 'authorized_keys' on the server. ++ +---- +$ git clone ssh://gimrr@/~gimrr/my_project +---- + +* *add gimrr user* ++ +Now you need to add your gimrr user to cloned repo config. This has to be +the 'GIMRR_USER' assigned your public key on the server. ++ +---- +$ git -C my_project config mr.user +---- + +* *fetch gimrr's data* ++ +---- +$ cd my_project +$ git mr-fetch -A +---- + REF TYPES --------- -This is the core of 'git-mr' and all data are tracked using the following three -refs. - -head -~~~~ -This is just a ref to the commit from which the MR was created. - -tags -~~~~ -Ref to commit with user's current set of tags for a specific MR. It's -a git tree with a single 'tags' files in a specific format. It can be -viewed by using e.g. 'git show refs/mrs///tags:tags'. - -mbox -~~~~ -Ref to user's comments for a specific MR. It's an empty git tree and each -commit represents user's reply, which is stored as commit description. -These refs are used to generate MR mboxes and the format -can be viewed by using e.g. 'git log refs/mrs///mbox'. +This is the core of 'git-mr' and all data are tracked using the following four +refs. Each ref has to point to the commit object in specific format and has to +follow the default policy, which is enforced by the +link:git-mr-update.html[git-mr-update(1)] used as git's update hook on server. + +. *head* - 'refs/mrs///head' ++ +This is just a ref to the commit from which the MR was created. It does +not contain any MR context data. Fully defined MR also needs 'mr' and +'tags' refs pointing to commits with tags file in correct format and with +proper tags under the same '/' namespace. + +. *mr* - 'refs/mrs///mr' ++ +This points to a commit containing git tree with a single file named tags. +The following tags, which describe the basic MR attributes, have to be +presented. ++ +Basic tags describing MR ++ + 'M': MR SHA-1 + 'B': MR base SHA-1 + 'A': MR author + 'C': MR commit list + 'CC': MR commit count + 'AN': MR author name + 'AE': MR author email + 'AT': MR author date, UNIX timestamp ++ +The tags file format is the same as described in the 'tags' ref type. The +difference is that all required tags have to be presented in 'mr' and they +cannot be changed. + +. *tags* - 'refs/mrs///tags' ++ +Reference to a commit with user's current set of tags for a specific MR. It's +a git tree with a single file named tags in the following format. ++ +File format of tags file ++ +---- +@m <1> +@u <2> +@c <3> + <4> + +@c +... +---- + <1> @m identifies MR to which the tags in this file belong + <2> @u user who created the tags + <3> @c commit to which the tags on the following lines belong + <4> tag and it's value for commit (3) in MR (1) owned by (2) ++ +The content of tags file can be viewed by using e.g. +'git show refs/mrs///tags:tags'. Each file +contains current set of tags, but history of changes is preserved and +can be viewed by e.g 'git log refs/mrs///tags'. ++ +Tags files referenced by 'mr' and 'tags' refs are concatenated and parsed +into internal structure used by 'git-mr' commands. This allows each +user to have a separate namespace and push tag changes without collisions +with others, while 'git-mr' commands can work with tags for whole MRs. + +. *mbox* - 'refs/mrs///mbox' ++ +Reference to user's comments for a specific MR. It's an empty git tree and each +commit represents one user's reply, which is stored as a commit description. ++ +Commit message format for mbox ++ +---- +To: <1> +In-Reply-To: <2> + <3> +<4> +---- + <1> 'To:' email header. + <2> 'In-Reply-To:' email header in gimrr's format. The 'mr' is MR SHA-1 to + which this comment belongs to and 'commit' is SHA-1 of MR commit or + another reply. Note that even replies/comments are identified by their + SHA-1. + <3> empty line delimiter of email headers + <4> email body ++ +Other email headers like 'Subject:', 'Date:' and 'From:' are received directly +from git. The final email is generated by simply calling 'git-show' with +specific format string. ++ +The 'mbox' refs are used to generate MR mboxes and for MR review from command +line. User's reply to a specific MR can be viewed by using e.g. +'git log refs/mrs///mbox'. + +CONTRIBUTION +------------ +Gimrr is using gimrr, so to be able to contribute you will need to generate +ssh keys as described in the *CLIENT SETUP* section and send the public part +of the key to gimrr@gimrr.com. + SEE ALSO -------- -- 1.7.10.4