203 lines
8.8 KiB
Markdown
203 lines
8.8 KiB
Markdown
# the 'hub' ADC
|
|
|
|
In this document:
|
|
|
|
* <a href="#_a_home_grown_hub_for_git_repos">a home grown 'hub' for git repos</a>
|
|
* <a href="#_general_syntax">general syntax</a>
|
|
* <a href="#_Bob_s_commands">Bob's commands</a>
|
|
* <a href="#_Alice_s_just_looking_commands">Alice's "just looking" commands</a>
|
|
* <a href="#_Alice_s_action_commands">Alice's "action" commands</a>
|
|
* <a href="#_what_next_">what next?</a>
|
|
* <a href="#_note_to_the_admin_configuration_variables">note to the admin: configuration variables</a>
|
|
|
|
<a name="_a_home_grown_hub_for_git_repos"></a>
|
|
|
|
### a home grown 'hub' for git repos
|
|
|
|
This ADC (admin-defined command) helps collaboration among repos. The name is
|
|
in honor of github, which is the primary host for gitolite itself.
|
|
|
|
[Note that github is a web-based service, and does a lot more, like comments,
|
|
code reviews, etc., none of which are possible here. We're only talking about
|
|
some basic stuff to make the most common operations easier. In particular,
|
|
this system is not a replacement for normal project communications like
|
|
email!]
|
|
|
|
**Conventions used**: all through the following description, we will assume
|
|
that **Alice** has a repo **parent**, **Bob** has a fork of parent called
|
|
**child**, and he is asking Alice to pull a branch he made called **b1** from
|
|
child to parent.
|
|
|
|
In plain git (without using github or similar), the pull request process
|
|
starts with an email from Bob to Alice, followed by Alice running a `git fetch
|
|
<Bob's URL> b1` (optionally preceded by a `git remote add` for convenience of
|
|
long term use). Until this happens she can't see much detail about the
|
|
commits to be pulled.
|
|
|
|
**What this ADC does** is (a) collect all the pull requests she needs to look
|
|
at in one place, and (b) allow her to examine the changes with any combination
|
|
of `git log` and `git diff` options *without having to fetch the content
|
|
first*, and (c) act as a trusted intermediary to allow Alice to fetch *just
|
|
one branch* from Bob even if she does not have any access to Bob's repository!
|
|
|
|
In a situation where there may be lots of requests, being able to take a quick
|
|
look at them (and possibly reject some), without having to pull down anything
|
|
at all, could be very useful.
|
|
|
|
Once past that level, she could get the changes down to her workstation using
|
|
`git fetch` as normal. With this ADC, however, she has another alternative:
|
|
get them over to `parent` (her repo) on the same gitolite server, then later
|
|
do a normal `git fetch [origin]` to get it to her workstation. This has the
|
|
added advantage that other people, who may be watching her repo but not Bob's,
|
|
now get to see what Bob sent her and send comments etc.
|
|
|
|
<a name="_general_syntax"></a>
|
|
|
|
### general syntax
|
|
|
|
The general syntax is
|
|
|
|
ssh git@server hub <hub-command> <args>
|
|
|
|
<a name="_Bob_s_commands"></a>
|
|
|
|
#### Bob's commands
|
|
|
|
The following commands do not cause a fetch, and should be quite fast:
|
|
|
|
* Bob sends a pull request for branch b1 to repo parent. Notice he does not
|
|
mention Alice by name. This command expects a message to be piped/typed
|
|
in via STDIN [this message is meant to be transient and is not stored long
|
|
term; use email for more "permanent" communications].
|
|
|
|
echo "hi Alice, please pull" | ssh git@server hub request-pull child b1 [parent]
|
|
|
|
If `child` was created by a recent version of the 'fork' ADC (or the KDE
|
|
'clone' ADC), which records the name of the parent repo on a fork, and it
|
|
is *that* repo to which Bob wishes to send the pull request, the third
|
|
argument is optional.
|
|
|
|
* Bob lists the status (fetched/rejected/pending) of pull requests he has
|
|
made from his repo child to repo parent. (Note we don't say "accepted" but
|
|
"fetched"; see later for why):
|
|
|
|
ssh git@server hub request-status child [parent]
|
|
|
|
The second argument is optional the same way as the 3rd argument in the
|
|
previous command.
|
|
|
|
<a name="_Alice_s_just_looking_commands"></a>
|
|
|
|
#### Alice's "just looking" commands
|
|
|
|
* Alice lists requests waiting for her to check and possibly pull into
|
|
parent. For each waiting pull request, she will see a serial number, the
|
|
originating repo name (child, in our example), the requestor (Bob, here),
|
|
and the branch/tag-name (b1) being pulled:
|
|
|
|
ssh git@server hub list-requests parent
|
|
|
|
This command also takes an optional list of search strings that are OR-d
|
|
together and matched against the 'status' field. So saying
|
|
|
|
ssh git@server hub list-requests parent fetched pending
|
|
|
|
would list only items that were 'fetched' or 'pending' (meaning 'accepted'
|
|
and 'rejected' would not show up).
|
|
|
|
* Alice views request # 1 waiting to be pulled into parent. Shows the same
|
|
details as above for that request, followed by the message that Bob typed
|
|
in when he ran `request-pull`:
|
|
|
|
ssh git@server hub view-request parent 1
|
|
|
|
* Alice views the log of the branch she is being asked to pull. Note that
|
|
this does NOT involve a fetch, so it will be pretty fast. The log starts
|
|
from b1, and stops at a SHA that represents any of the branches in parent.
|
|
Alice can use any git-log options she wants to; for instance `--graph`,
|
|
`--decorate`, `--boundary`, etc., could be quite useful. However, she
|
|
can't use any GUI; it has to be 'git log':
|
|
|
|
ssh git@server hub view-log parent 1 <git log options>
|
|
|
|
Notice that the repo name Alice supplies is still her own, although the
|
|
log comes from the child repo that Bob wants Alice to pull from. It's
|
|
best if you think of this as "view the commits from pull request #1 in
|
|
'parent'".
|
|
|
|
* Alice views the diff between arbitrary commits on child:
|
|
|
|
ssh git@server hub view-diff parent 1 <git diff options>
|
|
|
|
Again, she mentions *her* reponame but the diff's come from `child`. Also
|
|
note that, due to restrictions on what characters are allowed in arguments
|
|
to ADCs, you probably can't do things like `pu^` or `master~3`, and have
|
|
to use SHAs instead.
|
|
|
|
<a name="_Alice_s_action_commands"></a>
|
|
|
|
#### Alice's "action" commands
|
|
|
|
* Alice doesn't like what she sees and decides to reject it. This command
|
|
expects some text on STDIN as the rejection message:
|
|
|
|
echo "hi Bob, your patch needs work; see email" | ssh git@server hub reject parent 1
|
|
|
|
* Alice likes what she sees so far and wants to fetch the branch Bob is
|
|
asking her to pull. Note that we are intentionally not using the word
|
|
"accept", because this command does not (and cannot, since it is running
|
|
on a bare repo on the server) do a pull. What it does is it fetches into
|
|
a branch whose name will be `requests/child/b1`.
|
|
|
|
Note that when multiple requests from the same repo (child) for the same
|
|
branch (b1) happen, each "fetch" overwrites the branch. This allows Bob
|
|
to continually refine the branch he is requesting for a pull based on
|
|
(presumably emailed) comments from Alice. In a way, this is a "remote
|
|
tracking branch", just like `refs/remotes/origin/b1`.
|
|
|
|
ssh git@server hub fetch parent 1
|
|
|
|
This command will actually fetch from child into parent, and may take time
|
|
when the changes are large. However all this is on the server so it does
|
|
not involve network traffic:
|
|
|
|
* Alice has fetched the stuff she wants, looked at it/tested it, and decides
|
|
to merge it into `parent`. Once that is done, she runs:
|
|
|
|
echo "thanks for the frobnitz patch Bob" | ssh git@server hub accept parent 1
|
|
|
|
to let Bob know next time he checks 'request-status'. Like the `reject`
|
|
sub-command, this is also just a status update; no actual 'git' changes
|
|
happen.
|
|
|
|
Notice the sequence of Alice's action commands: it's either 'reject', or a
|
|
'fetch' then 'accept'.
|
|
|
|
<a name="_what_next_"></a>
|
|
|
|
### what next?
|
|
|
|
At this point, you're done with the `hub` ADC. However, all this is on the
|
|
bare `parent.git` on the server, and nothing has hit Alice's workstation yet!
|
|
Alice will still have to run a fetch or a pull on her workstation if she wants
|
|
to check the code in detail, use a tool like gitk, and especially to
|
|
compile/test it. *Then* she decides whether to accept or reject the request,
|
|
which will have to be communicated via email, of course; see the second para
|
|
of this document ;-)
|
|
|
|
Finally, note that Alice does not actually need to use the `fetch` subcommand.
|
|
She can do the traditional thing and fetch Bob's repo/branch directly to her
|
|
*workstation*.
|
|
|
|
<a name="_note_to_the_admin_configuration_variables"></a>
|
|
|
|
### note to the admin: configuration variables
|
|
|
|
There are 2 configuration variables. `BASE_FETCH_URL` should be set to a
|
|
simple "read" URL (so it doesn't even have to be ssh) that almost anyone using
|
|
this server can use. It's only used in producing the `git fetch` command
|
|
mentioned just above.
|
|
|
|
`GL_FORKED_FROM` is set to `gl-forked-from` by default, but if your initials
|
|
are `JM` you can set it to `kde-cloned-from` to save time and trouble ;-)
|