Advanced Topics

This final page covers advanced concepts you'll encounter when working with an immutable, content-addressed system like Arweave. It also serves as a quick reference for all the commands we've discussed.

1. Advanced Concepts

Understanding clone vs. pull (The Immutable Model)

In a traditional Git workflow (like with GitHub), git pull fetches new commits from a mutable remote server and merges them into your local branch.

This concept does not exist in Permagit.

Arweave is a permaweb—it is write-only, or more accurately, append-only. When you git push permagit, you are not updating a server; you are creating a brand new, permanent, immutable snapshot of your repository. This snapshot is given a unique Arweave Transaction ID (TX ID).

• To "clone" a repo: You use the permagit clone [tx-id] command. This fetches the specific repository snapshot associated with that transaction and rehydrates it into a local .git repository.

  permagit clone aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890-aBc

• To get "updates": You cannot pull changes. You must get the new Transaction ID from the developer who pushed the latest update. You would then clone this new transaction.

How do I find the latest version?

Since each push creates a new, independent transaction, Permagit links these transactions on-chain.

You can use the permagit log command to query the Solana blockchain (or a supporting indexer) for the history of a specific repository. This command looks up all push transactions signed by the repository's owner wallet.

# This command will return a list of Transaction IDs,
# from newest to oldest, for a given repo.
permagit log [repository-id-or-owner-wallet]

This allows you to find the TX ID for the "latest" version to clone.

2. Security: A Final Reminder

• NOT YOUR KEYS, NOT YOUR CODE. Your Solana wallet's keypair file is your identity, your password, and your encryption key all in one.

• If you lose your keypair file, you permanently lose the ability to decrypt your private repositories. There is no recovery mechanism.

• NEVER commit your id.json or keypair file to a Git repository—not even a private one. Store it securely and back it up offline.

3. CLI Command Reference

Here is a summary of the most common permagit commands.

Identity & Authentication

Command	Description
permagit login	Authenticates the CLI using your Solana keypair file.
permagit whoami	Displays the public key of the currently logged-in wallet.

Repository Management

Command	Description
permagit init	Sets up Permagit as a remote in your current Git repo.
permagit init --private	Initializes the repo in private (encrypted) mode.
permagit private on	Converts an existing repo to private mode.
permagit private off	Converts an existing repo to public mode.
git push permagit [branch]	Bundles, (encrypts if private), and uploads your repo to Arweave.
permagit clone <tx-id>	Downloads and unpacks a repository from Arweave.
permagit log <repo-id>	Shows the on-chain push history (all TX-IDs) for a repo.

Funding & Storage

Command	Description
permagit irys --status	Checks your current Arweave storage balance on Irys.
permagit irys --fund <amount>	Funds your Irys account with SOL from your wallet.

General

Command	Description
permagit --help	Displays a full list of all available commands and options.
permagit --version	Shows the currently installed version of the CLI.

---

Thank you for choosing Permagit to secure your code on the permaweb.