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/<mr>/<username>/{head,tags,mbox}', where
-'<mr>' is MR's SHA-1 identifier, <username> 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/<mr-sha-1>/<username>/{head,mr,tags,mbox}', where
+'<mr-sha-1>' is MR's SHA-1 identifier, <username> 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 <username> by yourself.
++
+----
+$ git config mr.user <username>
+----
+
+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\"" <public key>
+----
+
+
+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@<server>/~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 <username>
+----
+
+* *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/<mr>/<username>/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/<mr>/<username>/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/<mr-sha-1>/<username>/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 '<mr-sha-1>/<username>' namespace.
+
+. *mr* - 'refs/mrs/<mr-sha-1>/<username>/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/<mr-sha-1>/<username>/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 <mr-sha-1> <1>
+@u <username> <2>
+@c <commit-sha-1> <3>
+<tag-name> <tag-value> <4>
+<tag-name> <tag-value>
+@c <commit-sha-1>
+...
+----
+ <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/<mr>/<username>/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/<mr>/<username>/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/<mr-sha-1>/<username>/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: <email> <1>
+In-Reply-To: <mr.commit@localhost> <2>
+<empty line> <3>
+<msg><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/<mr>/<username>/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
--------
projects / gimrr.git / commitdiff