Your first repository

In this tutorial you will create a small private repository, add a README, then propose and merge a change. You only need a text editor, a Pillion account and Git on your computer. If the words “repository” and “commit” are new, start with Git and Pillion basics.

1. Get Git ready

Open a terminal: Terminal on macOS or Linux, or Git Bash on Windows. A terminal is a place to type commands. Enter each command on its own line and press Enter; wait for it to finish before continuing.

git --version

If you see a Git version number, you are ready. If the command is not found, follow the official Git installation instructions for your computer, then reopen the terminal. The examples below work in Git Bash as well as macOS and Linux terminals.

Set the name and email Git will record on your commits. Replace both example values with yours:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

These settings apply to your Git work on this computer. They identify the author of a commit; they do not sign you in to Pillion. Your commit email travels with the repository’s history, so use an address you intend to share. See Git’s first-time setup guide for changing these settings for individual repositories.

2. Sign in and create a repository

Open Sign in in your browser. Enter your email address and follow the emailed code or sign-in link. Choose a username if you are creating an account. If you do not yet have access, join the waitlist.

1. Open New repository.
2. Select your personal account as the Owner and enter hello-pillion as the repository name.
3. Choose Private, so only people with access can read it.
4. Leave Object format at its default, SHA-1, and select Create repository.

You now have an empty repository on Pillion. Its address contains your username and hello-pillion. The object-format reference explains that advanced setting if you need it later.

3. Give Git permission to connect

Being signed in in your browser does not sign in the Git program on your computer. Git connects over HTTPS using a personal access token: a secret you create for a specific set of tasks.

1. Open Settings → Access tokens.
2. Select your personal account as the owner.
3. Set Contents to write, which allows uploading changes as well as reading files.
4. Turn on Limit to selected repositories and select hello-pillion.
5. Select Generate new token and save the value in your password manager. Pillion shows it only once.

When Git prompts you later, enter your Pillion username and use this token as the password. A terminal may show no characters while you paste a password; that is normal. Never put the token in your files or repository URL. For other connection options, see Authentication and API.

4. Download your working copy

On the repository page, copy its HTTPS clone URL. In your terminal, move to a folder where you keep your work. For example, cd ~/Documents opens your Documents folder if it exists.

Replace YOUR-USERNAME below with your username, or replace the whole URL with the one you copied:

git clone https://pillion.dev/YOUR-USERNAME/hello-pillion.git
cd hello-pillion

clone creates the local hello-pillion folder and remembers Pillion’s address as origin. cd moves your terminal into that folder. A message saying you cloned an empty repository is expected at this stage.

5. Record your first file

Open the new folder in your text editor. Create a plain text file named README.md, paste the following text into it and save it:

# Hello Pillion

This is my first repository.

A README introduces a repository to its readers. The .md extension means Markdown, a text format where # starts a heading. Make sure your editor saves the filename as README.md, without an extra .txt extension.

git status
git add README.md
git diff --staged

status should list your new file. add selects it for the next commit. diff --staged shows the selected changes; you should see the text you wrote. Press q if Git opens a scrolling view.

git commit -m "Add a README"
git branch -M main
git push -u origin main

The first command records the file with a message. The second names this new repository’s initial branch main. The third sends that branch to Pillion; -u remembers where future pushes should go.

Refresh the repository page. You should see README.md and your commit. This first commit gives your otherwise empty repository a starting point for later changes.

6. Propose a change on a branch

A branch lets you prepare a change before adding it to the shared main branch. Create one:

git switch -c improve-readme

In your editor, add the sentence “I am learning how to share changes with Git.” to README.md and save it. Then run:

git diff
git add README.md
git commit -m "Explain what I am learning"
git push -u origin improve-readme

The change is now on Pillion’s improve-readme branch. It has not changed main. In the browser:

1. Open the repository’s Pull requests page and choose New pull request.
2. Select main as the base, the branch you want to change.
3. Select improve-readme as the head, the branch with your proposed change.
4. Give it the title “Explain what I am learning”, describe the change and select Create pull request.

You should see a pull request containing your added sentence. Its diff lets someone review the change without reading the whole repository.

7. Merge and update your computer

For this personal practice repository, read your own diff and use the merge panel when it says the pull request is ready. Create a merge commit combines the branch into main while preserving its commits. In a team repository, wait for the required reviews and checks first.

After Pillion shows the pull request as merged, bring that result back to your computer:

git switch main
git pull --ff-only

Open README.md again: your new sentence should now be there on main. You have completed the cycle from a local edit to a reviewed change in the shared repository.

If something does not match

• “Not a git repository”: your terminal is in the wrong folder. Use cd to enter the folder you cloned.
• “Author identity unknown”: complete the name and email setup in step 1.
• “Nothing to commit”: save your file in the editor and run git status. Check that you edited the file in this repository.
• Authentication failed: use the token as the password and check its owner, selected repository and Contents permission.
• Push rejected or merge blocked: read the message before retrying. The everyday Git guide explains how to investigate.

Next: use the same cycle for real work

Continue with Everyday Git for keeping up with teammates, fixing mistakes and resolving conflicts, or Pull requests and issues for reviewing work together.