Files
heartwood/radicle-cli/examples/rad-patch-via-push.md
T
cloudhead 1d167581f2 cob: Introduce xyz.radicle.id COB
Introduces a new COB type to store repository identity documents.

The reason for this change is to:

1. Simplify the code, as the identity document logic resembled a COB,
   yet it had custom logic. This allows existing COB code to be used for
   identities.
2. Make identity document update logic more flexible, since COB actions
   can be added in the future.
3. Re-purpose existing tools around COBs to work on identities, eg. `rad
   cob`.
4. Unify the concept of an identity change proposal, with regular identity
   changes. This means we can remove the `id.proposal` COB in favor of
   using the `id` COB itself.

Notes
-----

* Each repository has one Identity COB.
* The `Proposal` COB has been repurposed into the `Identity` COB.
* Identity documents are stored as *embeds* inside the Identity COB
  actions.
* The action that contains new document versions is called `revision`,
  just like the Patches COB.
* The namespaced `rad/id` ref is a symbolic reference to that Identity
  COB.
* The canonical `rad/id` ref is a direct reference to the commit in the
  Identity COB that contains the latest *accepted* revision of the
  document.
* All commands for managing identities have been folded into `rad id`.
  Hence `rad delegate` and `rad edit` are removed.
* The concept of "rebasing" an identity document is gone.
* The `rad id` output has been updated to match the style of other
  commands.
* When a revision has enough signatures, it is automatically adopted as
  the current identity, there is no longer the need for a "commit"
  action.
* When an identity revision is proposed, and the current identity has a
  threshold of `1`, that identity is automatically accepted due to the
  above point.
* The idea of "verifying a peer's identity branch" no longer applies, as
  COBs cannot be verified one history at a time.
* Since the root commit of the Identity COB does not have a "Resource"
  to point to (it would have to point to itself, which is impossible),
  we've made the resource id optional for COBs.
2023-10-12 17:32:33 +02:00

12 KiB

Using git push to open patches

Let's checkout a branch, make a commit and push to the magic ref refs/patches. When we push to this ref, a patch is created from our commits.

$ git checkout -b feature/1
Switched to a new branch 'feature/1'
$ git commit -a -m "Add things" -q --allow-empty
$ git push -o patch.message="Add things #1" -o patch.message="See commits for details." rad HEAD:refs/patches
✓ Patch e49e64637ab4a29e5a16c73000dacd2afa918d9d opened
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
 * [new reference]   HEAD -> refs/patches

We can see a patch was created:

$ rad patch show e49e64637ab4a29e5a16c73000dacd2afa918d9d
╭────────────────────────────────────────────────────╮
│ Title     Add things #1                            │
│ Patch     e49e64637ab4a29e5a16c73000dacd2afa918d9d │
│ Author    z6MknSL…StBU8Vi (you)                    │
│ Head      42d894a83c9c356552a57af09ccdbd5587a99045 │
│ Branches  feature/1                                │
│ Commits   ahead 1, behind 0                        │
│ Status    open                                     │
│                                                    │
│ See commits for details.                           │
├────────────────────────────────────────────────────┤
│ 42d894a Add things                                 │
├────────────────────────────────────────────────────┤
│ ● opened by z6MknSL…StBU8Vi (you) [   ...    ]     │
╰────────────────────────────────────────────────────╯

If we check our local branch, we can see its upstream is set to track a remote branch associated with this patch:

$ git branch -vv
* feature/1 42d894a [rad/patches/e49e64637ab4a29e5a16c73000dacd2afa918d9d] Add things
  master    f2de534 [rad/master] Second commit

Let's check that it's up to date with our local head:

$ git status --short --branch
## feature/1...rad/patches/e49e64637ab4a29e5a16c73000dacd2afa918d9d
$ git fetch
$ git push

And let's look at our local and remote refs:

$ git show-ref
42d894a83c9c356552a57af09ccdbd5587a99045 refs/heads/feature/1
f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354 refs/heads/master
f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354 refs/remotes/rad/master
42d894a83c9c356552a57af09ccdbd5587a99045 refs/remotes/rad/patches/e49e64637ab4a29e5a16c73000dacd2afa918d9d
$ git ls-remote rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji 'refs/heads/patches/*'
42d894a83c9c356552a57af09ccdbd5587a99045	refs/heads/patches/e49e64637ab4a29e5a16c73000dacd2afa918d9d
$ git ls-remote rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi 'refs/cobs/*'
2317f74de0494c489a233ca6f29f2b8bff6d4f15	refs/cobs/xyz.radicle.id/2317f74de0494c489a233ca6f29f2b8bff6d4f15
e49e64637ab4a29e5a16c73000dacd2afa918d9d	refs/cobs/xyz.radicle.patch/e49e64637ab4a29e5a16c73000dacd2afa918d9d

We can create another patch:

$ git checkout -b feature/2 -q master
$ git commit -a -m "Add more things" -q --allow-empty
$ git push rad HEAD:refs/patches
✓ Patch b1fd7b6883dca2ef11e0e486a7097e759ea90cdb opened
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
 * [new reference]   HEAD -> refs/patches

We see both branches with upstreams now:

$ git branch -vv
  feature/1 42d894a [rad/patches/e49e64637ab4a29e5a16c73000dacd2afa918d9d] Add things
* feature/2 8b0ea80 [rad/patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb] Add more things
  master    f2de534 [rad/master] Second commit

And both patches:

$ rad patch
╭────────────────────────────────────────────────────────────────────────────────────╮
│ ●  ID       Title            Author                  Head     +   -   Updated      │
├────────────────────────────────────────────────────────────────────────────────────┤
│ ●  b1fd7b6  Add more things  z6MknSL…StBU8Vi  (you)  8b0ea80  +0  -0  [    ...   ] │
│ ●  e49e646  Add things #1    z6MknSL…StBU8Vi  (you)  42d894a  +0  -0  [    ...   ] │
╰────────────────────────────────────────────────────────────────────────────────────╯

To update our patch, we simply push commits to the upstream branch:

$ git commit -a -m "Improve code" -q --allow-empty
$ git push
✓ Patch b1fd7b6 updated to c867846b9f294c271e8934820dfac2c5924ecd5a
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
   8b0ea80..02bef3f  feature/2 -> patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb

This last git push worked without specifying an upstream branch despite the local branch having a different name than the remote. This is because Radicle configures repositories upon rad init with push.default = upstream:

$ git config --local --get push.default
upstream

This allows for pushing to the remote patch branch without using the full <src>:<dst> syntax.

We can then see that the patch head has moved:

$ rad patch show b1fd7b6
╭──────────────────────────────────────────────────────────────────────────────╮
│ Title     Add more things                                                    │
│ Patch     b1fd7b6883dca2ef11e0e486a7097e759ea90cdb                           │
│ Author    z6MknSL…StBU8Vi (you)                                              │
│ Head      02bef3fac41b2f98bb3c02b868a53ddfecb55b5f                           │
│ Branches  feature/2                                                          │
│ Commits   ahead 2, behind 0                                                  │
│ Status    open                                                               │
├──────────────────────────────────────────────────────────────────────────────┤
│ 02bef3f Improve code                                                         │
│ 8b0ea80 Add more things                                                      │
├──────────────────────────────────────────────────────────────────────────────┤
│ ● opened by z6MknSL…StBU8Vi (you) [   ...    ]                               │
│ ↑ updated to c867846b9f294c271e8934820dfac2c5924ecd5a (02bef3f) [   ...    ] │
╰──────────────────────────────────────────────────────────────────────────────╯

And we can check that all the refs are properly updated in our repository:

$ git rev-parse HEAD
02bef3fac41b2f98bb3c02b868a53ddfecb55b5f
$ git status --short --branch
## feature/2...rad/patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb
$ git rev-parse refs/remotes/rad/patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb
02bef3fac41b2f98bb3c02b868a53ddfecb55b5f
$ git ls-remote rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi refs/heads/patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb
02bef3fac41b2f98bb3c02b868a53ddfecb55b5f	refs/heads/patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb

Force push

Sometimes, it's necessary to force-push a patch update. For example, if we amended the commit and want the updated patch to reflect that.

Let's try.

$ git commit --amend -m "Amended commit" --allow-empty
[feature/2 9304dbc] Amended commit
 Date: [..]

Now let's push to the patch head.

$ git push
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
 ! [rejected]        feature/2 -> patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb (non-fast-forward)
error: failed to push some refs to 'rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi'
hint: [..]
hint: [..]
hint: [..]
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

The push fails because it's not a fast-forward update. To remedy this, we can use --force to force the update.

$ git push --force
✓ Patch b1fd7b6 updated to cf4d8577a1ec8aaa21a7ccca67ad8627c3304024
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
 + 02bef3f...9304dbc feature/2 -> patches/b1fd7b6883dca2ef11e0e486a7097e759ea90cdb (forced update)

That worked. We can see the new revision if we call rad patch show:

$ rad patch show b1fd7b6
╭──────────────────────────────────────────────────────────────────────────────╮
│ Title     Add more things                                                    │
│ Patch     b1fd7b6883dca2ef11e0e486a7097e759ea90cdb                           │
│ Author    z6MknSL…StBU8Vi (you)                                              │
│ Head      9304dbc445925187994a7a93222a3f8bde73b785                           │
│ Branches  feature/2                                                          │
│ Commits   ahead 2, behind 0                                                  │
│ Status    open                                                               │
├──────────────────────────────────────────────────────────────────────────────┤
│ 9304dbc Amended commit                                                       │
│ 8b0ea80 Add more things                                                      │
├──────────────────────────────────────────────────────────────────────────────┤
│ ● opened by z6MknSL…StBU8Vi (you) [   ...    ]                               │
│ ↑ updated to c867846b9f294c271e8934820dfac2c5924ecd5a (02bef3f) [   ...    ] │
│ ↑ updated to cf4d8577a1ec8aaa21a7ccca67ad8627c3304024 (9304dbc) [   ...    ] │
╰──────────────────────────────────────────────────────────────────────────────╯

Empty patch

If we try to open a patch without making any changes to our base branch (master), we should get an error:

$ git push rad master:refs/patches
To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
 ! [remote rejected] master -> refs/patches (patch commits are already included in the base branch)
error: failed to push some refs to 'rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi'