📝 Document git clone over ssh (#736)

* 📝 Document git clone over ssh

* 📝 New page about Git over SSH

* Add in TOC

* Update docs/hub/security-git-ssh.md

Co-authored-by: Julien Chaumond <[email protected]>

---------

Co-authored-by: Julien Chaumond <[email protected]>

docs/hub/_toctree.yml

@@ -192,6 +192,8 @@
     sections:
     - local: security-tokens
       title: User Access Tokens
+    - local: security-git-ssh
+      title: Git over SSH
     - local: security-gpg
       title: Signing Commits with GPG
     - local: security-malware

docs/hub/models-downloading.md

@@ -36,7 +36,9 @@ Since all models on the Model Hub are Git repositories, you can clone the models
 
 ```bash
 git lfs install
-git clone <MODEL URL>
+git clone [email protected]:<MODEL ID> # example: git clone [email protected]:bigscience/bloom
 ```
 
 If you have write-access to the particular model repo, you'll also have the ability to commit and push revisions to the model.
+
+Add your SSH public key to [your user settings](https://huggingface.co/settings/keys) to push changes and/or access private repos.

docs/hub/repositories-getting-started.md

@@ -84,9 +84,18 @@ Downloading repositories to your local machine is called *cloning*. You can use
 
 ```bash
 git clone https://huggingface.co/<your-username>/<your-model-name>
-cd <your-model-id>
+cd <your-model-name>
 ```
 
+You can clone over SSH with the following command:
+```bash
+git clone [email protected]:<your-username>/<your-model-name>
+cd <your-model-name>
+```
+
+You'll need to add your SSH public key to [your user settings](https://huggingface.co/settings/keys) to push changes or access private repositories.
+
+
 ### Set up
 
 Now's the time, you can add any files you want to the repository! 🔥

docs/hub/repositories-next-steps.md

@@ -45,15 +45,15 @@ For example, say you have an upstream repository, **upstream**, and you just cre
 2. Clone your fork repository:
 
 ```
-git lfs clone https://huggingface.co/me/myfork.git
+git clone git@hf.co:me/myfork
 ```
 
 3. Fetch non-LFS files:
 
 ```
 cd myfork
 git lfs install --skip-smudge --local # affects only this clone
-git remote add upstream https://huggingface.co/friend/upstream.git
+git remote add upstream git@hf.co:friend/upstream
 git fetch upstream
 ```
 

docs/hub/sample-factory.md

@@ -40,7 +40,7 @@ The command line arguments are:
 Hugging Face repositories can be downloaded directly using `git clone`:
 
 ```
-git clone <URL of HuggingFace Repo>
+git clone [email protected]:<Name of HuggingFace Repo> # example: git clone [email protected]:bigscience/bloom
 ```
 
 ## Using Downloaded Models with Sample-Factory

docs/hub/security-git-ssh.md

@@ -0,0 +1,66 @@
+# Git over SSH
+
+You can access and write data in repositories on huggingface.co using SSH (Secure Shell Protocol). When you connect via SSH, you authenticate using a private key file on your local machine.
+
+Some actions, such as pushing changes, or cloning private repositories, will require you to upload your SSH public key to your account on huggingface.co.
+
+You can use a pre-existing SSH key, or generate a new one specifically for huggingface.co.
+
+## Checking for existing SSH keys
+
+If you have an existing SSH key, you can use that key to authenticate Git operations over SSH.
+
+SSH keys are usually located under `~/.ssh` on Mac & Linux, and under `C:\\Users\\<username>\\.ssh` on Windows. List files under that directory and look for files of the form:
+
+- id_rsa.pub
+- id_ecdsa.pub
+- id_ed25519.pub
+
+Those files contain your SSH public key.
+
+If you don't have such file under `~/.ssh`, you will have to [generate a new key](#generating-a-new-ssh-keypair). Otherwise, you can [add your existing SSH public key(s) to your huggingface.co account](#add-a-ssh-key-to-your-account).
+
+## Generating a new SSH keypair
+
+If you don't have any SSH keys on your machine, you can use `ssh-keygen` to generate a new SSH key pair (public + private keys):
+
+```
+$ ssh-keygen -t ed25519 -C "[email protected]"
+```
+
+We recommend entering a passphrase when you are prompted to. A passphrase is an extra layer of security: it is a password that will be prompted whenever you use your SSH key.
+
+Once your new key is generated, add it to your SSH agent with `ssh-add`:
+
+```
+$ ssh-add ~/.ssh/id_ed25519
+```
+
+If you chose a different location than the default to store your SSH key, you would have to replace `~/.ssh/id_ed25519` with the file location you used.
+
+## Add a SSH key to your account
+
+To access private repositories with SSH, or to push changes via SSH, you will need to add your SSH public key to your huggingface.co account. You can manage your SSH keys [in your user settings](https://huggingface.co/settings/keys).
+
+To add a SSH key to your account, click on the "Add SSH key" button.
+
+Then, enter a name for this key (for example, "Personal computer"), and copy and paste the content of your **public** SSH key in the area below. The public key is located in the `~/.ssh/id_XXXX.pub` file you found or generated in the previous steps.
+
+Click on "Add key", and voilà! You have added a SSH key to your huggingface.co account.
+
+
+## Testing your SSH authentication
+
+Once you have added your SSH key to your huggingface.co account, you can test that the connection works as expected.
+
+In a terminal, run:
+```
+$ ssh -T [email protected]
+```
+
+If you see a message with your username, congrats! Everything went well, you are ready to use git over SSH.
+
+Otherwise, if the message states something like the following, make sure your SSH key is actually used by your SSH agent.
+```
+Hi anonymous, welcome to Hugging Face.
+```

docs/hub/security.md

@@ -9,6 +9,7 @@ Hugging Face is also [SOC2 Type 1 certified](https://us.aicpa.org/interestareas/
 ## Contents
 
 - [User Access Tokens](./security-tokens)
+- [Git over SSH](./security-git-ssh)
 - [Signing commits with GPG](./security-gpg)
 - [Malware Scanning](./security-malware)
 - [Pickle Scanning](./security-pickle)

docs/sagemaker/inference.md

@@ -173,7 +173,7 @@ Create your own `model.tar.gz` from a model from the 🤗 Hub:
 
 ```bash
 git lfs install
-git clone https://huggingface.co/{repository}
+git clone git@hf.co:{repository}
 ```
 
 2. Create a `tar` file: