diff --git a/i2p2www/blog/2020/03/06/git-over-i2p.rst b/i2p2www/blog/2020/03/06/git-over-i2p.rst new file mode 100644 index 00000000..bb9903f0 --- /dev/null +++ b/i2p2www/blog/2020/03/06/git-over-i2p.rst @@ -0,0 +1,268 @@ +====================== +{% trans -%}Git over I2P for Users{%- endtrans %} +====================== + +.. meta:: + :author: idk + :date: 2019-05-20 + :excerpt: {% trans %}Help Bootstrap I2P-Bote!{% endtrans %} + +{% trans -%} +Tutorial for setting up git access through an I2P Tunnel. This tunnel +will act as your access point to a single git service on I2P. It is part of the +overall effort to transition I2P from monotone to Git. +{%- endtrans %} + +{% trans -%}Before anything else: Know the capabilities the service offers to the public{%- endtrans %} +------------------------------------------------------------------------------------------------------- + +{% trans -%} +Depending on how the git service is configured, it may or may not offer +all services on the same address. In the case of git.idk.i2p, there is a +public HTTP URL, but this URL is read-only and cannot be used to make +changes. To do that, you must also know the SSH base32, which isn’t +public at this time. Unless I’ve told you the SSH base32 to git.idk.i2p, +head over to the `Server `__ tutorial to set up your own. +{%- endtrans %} + +{% trans -%}First: Set up an account at a Git service{%- endtrans %} +-------------------------------------------------------------------- + +{% trans -%} +To create your repositories on a remote git service, sign up for a user +account at that service. Of course it’s also possible to create +repositories locally and push them to a remote git service, but most +will require an account and for you to create a space for the repository +on the server. Gitlab has a very simple sign-up form: +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/register.png + :alt: Registration is easy! + + Registration is easy! + +{% trans -%}Second: Create a project to test with{%- endtrans %} +---------------------------------------------------------------- + +{% trans -%} +To make sure the setup process works, it helps to make a repository to +test with from the server, and for the sake of this tutorial, we’re +going to use a fork of the I2P router. First, browse to the +i2p-hackers/i2p.i2p repository: +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/explore.png + :alt: Browse to i2p.i2p + +.. class:: screenshot +.. figure:: /_static/images/git/i2p.png + :alt: I2P Hackers i2p.i2p + +{% trans -%} +Then, fork it to your account. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/fork.png + :alt: Roger is forking + +.. class:: screenshot +.. figure:: /_static/images/git/forked.png + :alt: Roger is finished + +{% trans -%}Third: Set up your git client tunnel{%- endtrans %} +--------------------------------------------------------------- + +{% trans -%} +To have read-write access to my server, you’ll need to set up a tunnel +for your SSH client. As an example, we’re going to use the HTTP tunnel +instead, but if all you need is read-only, HTTP/S cloning, then you can +skip all this and just use the http_proxy environment variable to +configure git to use the pre-configured I2P HTTP Proxy. For example: +{%- endtrans %} + +:: + + http_proxy=http://localhost:4444 git clone http://git.idk.i2p/welshlyluvah1967/i2p.i2p + +.. class:: screenshot +.. figure:: /_static/images/git/wizard1.png + :alt: Client tunnel + +.. class:: screenshot +.. figure:: /_static/images/git/wizard2.png + :alt: Git over I2P + +{% trans -%} +Then, add the address you will be pushing and pulling from. Note that +this example address is for Read-Only HTTP-over-I2P clones, if your +admin does not allow the git HTTP(Smart HTTP) protocol, then you will +need to get the SSH clone base32 from them. If you have an SSH clone +base32, substitute it for the base32 in this step, which will fail. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/wizard3.png + :alt: git.idk.i2p + +{% trans -%} +Pick a port to forward the I2P service to locally. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/wizard4.png + :alt: localhost:localport + +{% trans -%} +I use it alot, so I start my client tunnel automatically, but it’s up to +you. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/wizard5.png + :alt: Auto Start + +{% trans -%} +When you’re all done, it should look alot like this. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/wizard6.png + :alt: Review settings + +{% trans -%}Fourth: Attempt a clone{%- endtrans %} +-------------------------------------------------- + +{% trans -%} +Now your tunnel is all set up, you can attempt a clone over SSH. +{%- endtrans %} + +:: + + GIT_SSH_COMMAND="ssh -p 7442" \ + git clone git@127.0.0.1:welshlyluvah1967/i2p.i2p + +{% trans -%} +You might get an error where the remote end hangs up unexpectedly. +Unfortunately git still doesn’t support resumable cloning. Until it +does, there are a couple fairly easy ways to handle this. The first and +easiest is to try and clone to a shallow depth: +{%- endtrans %} + +:: + + GIT_SSH_COMMAND="ssh -p 7442" \ + git clone --depth 1 git@127.0.0.1:welshlyluvah1967/i2p.i2p + +{% trans -%} +Once you’ve performed a shallow clone, you can fetch the rest resumably +by changing to the repo directory and running: +{%- endtrans %} + +:: + + git fetch --unshallow + +{% trans -%} +At this point, you still don’t have all your branches yet. You can get +them by running the following commands: +{%- endtrans %} + +:: + + git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" + git fetch origin + +{% trans -%} +Which tells git to alter the repository configuration so that fetching +from origin fetches all branches. +{%- endtrans %} + +{% trans -%} +If that doesn’t work, you can try opening the tunnel configuration menu +and adding some backup tunnels. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/tweak2.png + :alt: Backup Tunnels + + Backup Tunnels + +{% trans -%} +If that doesn’t work, then the next easy thing to try is to decrease the +tunnel length. Don’t do this if you believe you are at risk of your +code-contribution activity being de-anonymized by a well-resourced +attacker seeking to run many malicious nodes and control your whole +path. If that sounds unlikely to you then you can probably do it safely. +{%- endtrans %} + +.. class:: screenshot +.. figure:: /_static/images/git/tweak1.png + :alt: One-Hop Tunnels + + One-Hop Tunnels + +{% trans -%}Suggested Workflow for Developers!{%- endtrans %} +------------------------------------------------------------- + +{% trans -%} +Revision control can make your life easier, but it works best if you use +it well! In light of this, we strongly suggest a fork-first, +feature-branch workflow as many are familiar with from Github. In such a +workflow, the master branch is used as a sort of “Trunk” for updates and +is never touched by the programmmer, instead, all changes to the master +are merged from branches. In order to do set up your workspace for this, +take the following steps: +{%- endtrans %} + +- {% trans -%}**Never make changes to the Master Branch**. You will be using the + master branch to periodially obtain updates to the official source + code. All changes should be made in feature branches.{%- endtrans %} + +1. {% trans -%}Set up a second remote in your local repository using the upstream + source code.{%- endtrans %} + + :: + + git remote add upstream git@127.0.0.1:i2p-hackers/i2p.i2p + +2. {% trans -%}Pull in any upstream changes on your current master:{%- endtrans %} + + :: + + git pull upstream master + +3. {% trans -%}Before making any changes to the source code, check out a new feature + branch to develop on:{%- endtrans %} + + :: + + git checkout -b feature-branch-name + +4. {% trans -%}When you’re done with your changes, commit them and push them to your + branch{%- endtrans %} + + :: + + git commit -am "I added an awesome feature!" + git push origin feature-branch-name + +5. {% trans -%}Submit a merge request. When the merge request is approved and + brought into the upstream master, check out the master locally and + pull in the changes:{%- endtrans %} + + :: + + git checkout master + git pull upstream master + +6. {% trans -%}Whenever a change to the upstream master(i2p-hackers/i2p.i2p) is + made, you can update your master code using this procedure as well.{%- endtrans %} + + :: + + git checkout master + git pull upstream master diff --git a/i2p2www/static/images/git/explore.png b/i2p2www/static/images/git/explore.png new file mode 100644 index 00000000..54f939fd Binary files /dev/null and b/i2p2www/static/images/git/explore.png differ diff --git a/i2p2www/static/images/git/fork.png b/i2p2www/static/images/git/fork.png new file mode 100644 index 00000000..43b3deac Binary files /dev/null and b/i2p2www/static/images/git/fork.png differ diff --git a/i2p2www/static/images/git/forked.png b/i2p2www/static/images/git/forked.png new file mode 100644 index 00000000..0cfa2459 Binary files /dev/null and b/i2p2www/static/images/git/forked.png differ diff --git a/i2p2www/static/images/git/i2p.png b/i2p2www/static/images/git/i2p.png new file mode 100644 index 00000000..adc59e92 Binary files /dev/null and b/i2p2www/static/images/git/i2p.png differ diff --git a/i2p2www/static/images/git/register.png b/i2p2www/static/images/git/register.png new file mode 100644 index 00000000..ced8c386 Binary files /dev/null and b/i2p2www/static/images/git/register.png differ diff --git a/i2p2www/static/images/git/tweak1.png b/i2p2www/static/images/git/tweak1.png new file mode 100644 index 00000000..7902c3a0 Binary files /dev/null and b/i2p2www/static/images/git/tweak1.png differ diff --git a/i2p2www/static/images/git/tweak2.png b/i2p2www/static/images/git/tweak2.png new file mode 100644 index 00000000..7716b33b Binary files /dev/null and b/i2p2www/static/images/git/tweak2.png differ diff --git a/i2p2www/static/images/git/wizard1.png b/i2p2www/static/images/git/wizard1.png new file mode 100644 index 00000000..f8fc0c4d Binary files /dev/null and b/i2p2www/static/images/git/wizard1.png differ diff --git a/i2p2www/static/images/git/wizard2.png b/i2p2www/static/images/git/wizard2.png new file mode 100644 index 00000000..8f5fe072 Binary files /dev/null and b/i2p2www/static/images/git/wizard2.png differ diff --git a/i2p2www/static/images/git/wizard3.png b/i2p2www/static/images/git/wizard3.png new file mode 100644 index 00000000..99ef99a3 Binary files /dev/null and b/i2p2www/static/images/git/wizard3.png differ diff --git a/i2p2www/static/images/git/wizard4.png b/i2p2www/static/images/git/wizard4.png new file mode 100644 index 00000000..7a0aaec3 Binary files /dev/null and b/i2p2www/static/images/git/wizard4.png differ diff --git a/i2p2www/static/images/git/wizard5.png b/i2p2www/static/images/git/wizard5.png new file mode 100644 index 00000000..f56ea5b7 Binary files /dev/null and b/i2p2www/static/images/git/wizard5.png differ diff --git a/i2p2www/static/images/git/wizard6.png b/i2p2www/static/images/git/wizard6.png new file mode 100644 index 00000000..990381ab Binary files /dev/null and b/i2p2www/static/images/git/wizard6.png differ