Quickstart for empty repositories 4edcf24025cf

<section class="quickstart" aria-labelledby="qs-title">

  <h2 id="qs-title">This repository is empty</h2>

  {% if q.can_push %}

  <p>Push to it from any Oxygen checkout. It takes the id of the first repository pushed, so clones made later share it.

  You need a personal access token with <code>repo:write</code>: <a href="/settings/tokens">create one</a> and put it where the commands say <code>YOUR-TOKEN</code>.</p>

  {% if q.ca_url.is_some() %}<p class="small mute">This hub uses a self-signed certificate, so the commands save it and point the remote at it.</p>{% endif %}

  <h3>Push an existing checkout</h3>

  {% let cmd = q.connect(repo.clone_url) %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <h3>Start from nothing</h3>

  {% let cmd = q.fresh(repo.name) %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p class="small">Then run the commands above.</p>

  <h3>Bring a Git branch</h3>

  {% let cmd = q.git_import(repo.name) %}

  <div class="cmds"><pre><code>{{ cmd }}</code></pre><button class="small" data-copy="{{ cmd }}">copy</button></div>

  <p class="small">Then run the commands above. Every Git commit becomes a change.</p>

  {% if repo.can(crate::auth::Access::Write) %}<p>Or <a href="{{ repo.url }}/newfile/{{ repo.default_bookmark }}">create the first file</a> in the browser.</p>{% endif %}

  {% else %}

  <p>Nothing has been pushed yet. Watch it to hear when something is.</p>

  {% endif %}

</section>

    /// Set while the repository has no changes (hub spec §6).

    quickstart: Option<Quickstart>,

}

/// A remote name from the hub's host: its first label when that is a

/// plain lowercase word (`earth` for `https://earth.example.org:7343`),

/// otherwise `hub`.

fn remote_name(base_url: &str) -> String {

    let host = base_url.split("://").nth(1).unwrap_or("").split(['/', ':']).next().unwrap_or("");

    let first = host.split('.').next().unwrap_or("");

    let plain = first.len() <= 20

        && first.starts_with(|c: char| c.is_ascii_lowercase())

        && first.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit());

    if plain && first != "www" && first != "localhost" {

        first.to_string()

    } else {

        "hub".to_string()

    }

}

/// The commands that get a first push into an empty repository, filled

/// in for this hub and this repository.

pub struct Quickstart {

    /// A remote name taken from the hub's host name (`earth` for

    /// `earth.example.org`), `hub` when that is not a plain word.

    pub remote: String,

    /// Where to download the hub's certificate, when it is self-signed.

    pub ca_url: Option<String>,

    /// Where the commands save that certificate.

    pub ca_file: String,

    /// Whether the viewer may push here.

    pub can_push: bool,

}

impl Quickstart {

    pub fn new(app: &Shared, can_push: bool) -> Quickstart {

        let base = app.config.base_url().trim_end_matches('/').to_string();

        let remote = remote_name(&base);

        let ca_file = format!("~/.config/oxy/{remote}-ca.pem");

        let ca_url = app.config.tls.self_signed.then(|| format!("{base}/.well-known/oxyhub-ca.pem"));

        Quickstart { remote, ca_url, ca_file, can_push }

    }

    /// Connect a checkout to this repository and push; the token line

    /// stays a placeholder so no secret is ever printed.

    pub fn connect(&self, clone_url: &str) -> String {

        let r = &self.remote;

        let mut s = format!("oxy remote add {r} {clone_url}\n");

        if let Some(ca) = &self.ca_url {

            s += &format!("curl -fsSL {ca} -o {}\n", self.ca_file);

            s += &format!("oxy config remote.{r}.ca {}\n", self.ca_file);

        }

        s += &format!("oxy config remote.{r}.token YOUR-TOKEN\n");

        s += &format!("oxy push {r}");

        s

    }

    /// Start a repository from nothing.

    pub fn fresh(&self, name: &str) -> String {

        format!("mkdir {name} && cd {name}\noxy init\necho \"# {name}\" > README.md\noxy commit -m \"First change\"")

    }

    /// Bring a Git branch across.

    pub fn git_import(&self, name: &str) -> String {

        format!("oxy git import --branch main path/to/git-checkout {name}\ncd {name}")

    }

    let quickstart = (o.changes == 0).then(|| Quickstart::new(&app, rs.can(crate::auth::Access::Write)));

    Ok(Page(OverviewPage { shell, repo: rs, o, readme_html, watching, latest_release, quickstart }))

#[cfg(test)]

mod tests {

    use super::remote_name;

    #[test]

    fn remote_names_come_from_the_host() {

        assert_eq!(remote_name("https://earth.andymccall.xyz:7343"), "earth");

        assert_eq!(remote_name("https://hub.example.org"), "hub");

        assert_eq!(remote_name("http://127.0.0.1:7300"), "hub");

        assert_eq!(remote_name("http://localhost:7300"), "hub");

        assert_eq!(remote_name("https://www.example.org"), "hub");

        assert_eq!(remote_name("https://My-Host.example"), "hub");

    }

}

#[tokio::test(flavor = "multi_thread")]

async fn empty_repository_shows_a_quickstart() {

    let h = hub().await;

    let app = &h.app;

    let andy = register(app, "andy").await;

    let bob = register(app, "bob").await;

    app.repos.create(&RepoName::parse("andy/fresh").unwrap(), None).unwrap();

    db::repos::create(&app.db, "andy", "fresh", "", hub_api::Visibility::Public).await.unwrap();

    let page = get(app, "/andy/fresh", Some(&andy)).await;

    assert!(page.body.contains("This repository is empty"), "{}", page.body);

    let clone_url = format!("{}/andy/fresh", h.base);

    assert!(page.body.contains(&format!("oxy remote add hub {clone_url}")), "{}", page.body);

    assert!(page.body.contains("oxy config remote.hub.token YOUR-TOKEN"));

    assert!(page.body.contains("oxy push hub"));

    assert!(

        page.body.contains("mkdir fresh && cd fresh") || page.body.contains("mkdir fresh && cd fresh"),

        "{}",

        page.body

    );

    assert!(page.body.contains("oxy git import --branch main"));

    assert!(!page.body.contains("oxyhub-ca.pem"), "no certificate step without a self-signed certificate");

    // A reader without write access is not told to push.

    let page = get(app, "/andy/fresh", Some(&bob)).await;

    assert!(page.body.contains("Nothing has been pushed yet") && !page.body.contains("oxy push hub"), "{}", page.body);

    // After a first push the quickstart gives way to the tree.

    let work = tempfile::tempdir().unwrap();

    let mut client = Repo::init(work.path()).unwrap();

    client.config.set("remote.hub.url", &clone_url).unwrap();

    client.config.set("remote.hub.token", "site").unwrap();

    client.save_config().unwrap();

    write(work.path(), "README.md", b"# fresh\n");

    client.commit("First change", &[]).unwrap();

    assert!(client.push("hub", false).unwrap().iter().all(|r| r.ok));

    let page = get(app, "/andy/fresh", Some(&andy)).await;

    assert!(!page.body.contains("This repository is empty") && page.body.contains("README.md"), "{}", page.body);

}

| `/{owner}/{name}` | Repository overview (§6.4); while empty, a quickstart with the exact commands for this hub (remote, certificate, token, push; start from nothing; import from Git) |

    {% if let Some(q) = quickstart %}

    {% include "quickstart.html" %}

    {% else %}

    {% endif %}

.quickstart { background: var(--panel); border: 1px solid var(--line); padding: 16px 20px; }

.quickstart h2 { margin-top: 0; }

.quickstart h3 { font-size: 14px; margin: 18px 0 6px; }

.cmds { display: flex; gap: 6px; align-items: flex-start; }

.cmds pre { flex: 1; margin: 0; background: var(--bg); border: 1px solid var(--line); padding: 8px 10px; overflow-x: auto; }

<p class="empty">Nothing here yet. <a href="{{ repo.url }}">The overview</a> shows how to make a first push.</p>