About This Guide
This guide provides detailed instructions for beginners to help you manage Xcode projects with GitHub. We’ll cover the essential steps, with special attention to setting up the important .gitignore file.
1 First, Create an Xcode Project
- Xcode → Create a new Xcode project
- When saving your project, do NOT check “Create Git repository on my Mac”
- We’ll learn how to set up Git manually!
While Xcode offers an option to create a Git repository automatically, this guide deliberately skips that option so you can learn the manual Git setup process. This will help you understand how Git works at a deeper level.
2 Open Terminal & Navigate to Your Project Folder
※ Replace “YourProjectName” with your actual project name!
Beginner’s Tip
The terminal command “cd” stands for “change directory” and it’s the command to navigate to a specified folder. If your project isn’t on the Desktop, adjust the path accordingly.
3 [IMPORTANT] Create a .gitignore File
What is .gitignore?
- It’s a file that tells Git “don’t upload these files”!
- For Xcode, there are several files you don’t want to upload to GitHub:
- DerivedData (build artifacts)
- .xcuserstate (your local settings)
- Personal configuration files
⇒ By excluding unnecessary files, your repository stays clean and you’ll avoid potential problems!
How to Create a .gitignore File
Create it in your project using Terminal:
Once created, edit the file. This command opens it with the default text editor on Mac:
Add the following content for Xcode projects:
Note
This is good enough to start with! (There are more detailed configurations available, but this is sufficient for beginners ✨)
Beginner’s Note
“touch” is a command that creates a new file if it doesn’t exist. Also, files starting with a “.” are “hidden files” on Mac and won’t normally be visible in Finder.
4 Initialize Git (git init)
→ This creates a local repository.
Beginner’s Explanation
The “git init” command initializes your current folder as a Git repository. This creates a hidden .git folder that will store your project’s change history and prepare it for version control.
5 Stage Files (git add)
※ Files excluded by .gitignore will be automatically ignored here, so don’t worry!
Explanation
The “.” in “git add .” means “all files in the current directory.” This command adds tracked files to the staging area, which is the preparation step before committing.
6 Make Your First Commit
Explanation
“git commit” records the changes to the staged files. The “-m” option allows you to include a commit message that briefly explains the changes. Good commit messages are very helpful when tracking changes in your project history later.
👉 Want to learn more about setting up and using Git on Mac? Check out this beginner-friendly guide!
7 Create a Repository on GitHub
- Login to GitHub in your browser
- Click the “+” icon in the top right → Select “New repository”
- Enter a repository name (typically the same as your project name)
- Add a description if needed
- Click the “Create repository” button
Important
Do NOT create a README file or .gitignore file at this stage. Create an empty repository, as we’ve already set up the project and Git locally.
8 Connect to the Remote Repository
Option 1: Using HTTPS (Recommended for Beginners)
※ Replace “yourusername” and “yourrepository” with your actual GitHub username and repository name.
Explanation
This command adds the URL of the remote repository to your local Git configuration. “origin” is the nickname for your remote repository, which will be used in subsequent operations.
Option 2: Using SSH (More Secure, No Password Required)
Why Use SSH?
Using SSH keys allows you to connect to GitHub without supplying your username and password each time. It’s more secure and convenient for regular GitHub users.
Step 1: Check for Existing SSH Keys
Look for files named id_rsa.pub, id_ecdsa.pub, or id_ed25519.pub. If they exist, you can skip to Step 3.
Step 2: Generate a New SSH Key
When prompted, press Enter to accept the default file location. Optionally, enter a secure passphrase.
Step 3: Add SSH Key to SSH Agent
Step 4: Copy SSH Key to Clipboard
This copies the contents of your public key file to your clipboard.
Step 5: Add SSH Key to GitHub
- Go to GitHub.com and sign in
- Click your profile photo in the top right, then click “Settings”
- In the left sidebar, click “SSH and GPG keys”
- Click “New SSH key”
- Enter a title (e.g., “My Mac”)
- Paste your key into the “Key” field
- Click “Add SSH key”
Step 6: Connect to Your Repository Using SSH
Important
The repository URL can be found in the “Quick setup” section of your newly created GitHub repository page. Make sure to switch to “SSH” before copying the URL. It should start with “git@github.com:” rather than “https://”.
If you’ve already added an HTTPS remote, you can change it to SSH with:
9 Push to GitHub
Important Note
In recent versions of Git, the default branch name has changed from “master” to “main”. If you get an error, try the following instead:
Explanation
The “git push” command uploads your committed changes to the remote repository (GitHub). The “-u” option (or “–set-upstream”) sets the default for future push/pull operations. After using it for the first push, you can simply use “git push” for subsequent pushes to the same remote branch.
🎯 Summary Table
| Step | Action | Command Example |
|---|---|---|
| 1 | Git initialization | git init |
| 2 | Create .gitignore | touch .gitignore + open -e .gitignore |
| 3 | Add files | git add . |
| 4 | Commit | git commit -m “Initial commit with .gitignore” |
| 5 | Set remote | git remote add origin <URL> |
| 6 | Push | git push -u origin main |
🛡️ Why is .gitignore Important?
- Keeps unnecessary files off GitHub = cleaner project
- Prevents security risks (avoid accidentally publishing personal info or password files)
- Prevents team development issues (avoids sharing environment-dependent files)
Therefore, make it a habit to always create a .gitignore file! 💪
Now you know how to manage Xcode projects with Git + create a clean repository + push to GitHub!
Next Steps
After learning the basic Git operations, you can advance to creating branches, merging, and pull requests to utilize Git even more effectively.
👉 Interested in serious iOS app development with Xcode? Check out this complete beginner’s guide!
Leave a Reply