News Tips & Tricks

Tutorial: Working with Git from AppCode

In this tutorial, we will guide you through the most popular Git operations used on a daily basis and show how they can be performed from the AppCode user interface. You will learn how to add projects to the Git repository, share them on GitHub, commit and push changes, create and merge branches, investigate the files’ history, and more.

Before you start

In this tutorial, we will create a simple project, share it on GitHub, and perform some Git tasks described below. If you want to use an existing shared project, clone it as described in Check out a project from a remote host (clone).

To create a new project, launch AppCode and click New Project on the Welcome screen.

If you have another project open in AppCode at the moment, select File | New Project from the main menu.

In the dialog that opens, select iOS | Application | Single View App and click Next:

Create project

Fill in the following fields:

  • Product Name: gitdemo.
  • Organization Name: your or your company’s name.
  • Organization Identifier: your company’s identifier in reverse-DNS format, for example, com.mycompany.

Select Swift in the list of languages and SwiftUI in the User Interface field. Make sure that all checkboxes are cleared and click Finish:

Create project

In the Finder window that opens, select a directory where your project will be located. The new project will immediately open in AppCode:

New project

Step 1. Enable version control integration

From the main menu, select VCS | Enable Version Control Integration. In the dialog that opens, select Git from the list of available version control systems and click OK.

Enable VCS

Alternatively, press ⌃V and select Create Git Repository (or press 1). In the Finder window that opens, specify a root folder for the local Git repository.

You will get a notification that the local Git repository has been created for your project. On the toolbar and status bar, the Git-related controls will appear:

After Git initialized

The dedicated tool windows for working with Git are now available: Commit (⌘K or View | Tool Windows | Commit) and Git (⌘9 or View | Tool Windows | Git).

Git toolwindow

From the Commit tool window ⌘K, you can review the local changes and commit them to the local Git repository. From the Git tool window, you can work with the Git log, manage pull requests from GitHub, and more.

Step 2. Add files to .gitignore

On the Local Changes tab of the Commit tool window ⌘K, you see the list of files that belong to your project. These files are not added to the Git repository yet — you need to select which of them you want to share and which ones should be ignored by the VCS.

Group the files by directories: press ⌃P or click the Group icon button on the toolbar and select Directory:

Group by directory

Select the directories that you don’t want to share. For example, the following directories may be ignored without breaking integrity of the project:

  • .idea: settings of your local AppCode installation. Ignore this directory unless you want to share your settings among the team members.
  • xcuserdata: user data and workspace settings of the Xcode project. These files are regenerated on project opening and usually don’t have to be shared.Add to .gitignore

Right-click the selection and choose Add to .gitignore | Add to .gitignore:

Add to .gitignore

You will be prompted to confirm creation of a new .gitignore file in the root directory of your project. Click Create. From the dialog that opens, you can either add the newly created file to Git right away by pressing Add or postpone this by pressing Cancel:

Add or cancel

Click Add. You will see that the .gitignore file has been added to the root directory of your project and placed to Default Changelist. The directories you selected to ignore are no longer displayed in the Unversioned Files list:

.gitignore added

Any time, you can edit the .gitignore file to add new directories to the list or remove existing ones. To show the ignored files again, click Show ignored on the toolbar.

Step 3. Commit your project to the local Git repository

Now, when all unnecessary directories are excluded from the list of unversioned files, you just need to add all the files to the repository and commit them to save their current state.

In the Commit tool window ⌘K, move all the files from the Unversioned Files list to Default Changelist using drag-and-drop or the Add to VCS command of the context menu (⌥⌘A). Select all files by clicking the root folder checkbox.

From the Commit tool window, you can also preview added and modified files, use the advanced commit options, add and exclude files from the commit, and more.

Type a message for your first commit in the Commit Message area:

Commit toolwindow

Click Commit. The corresponding notification appears once the commit is performed:

Commit nofication

Step 4. Share your project on GitHub

To make your project available for other contributors, you need to publish it to a remote repository, for example, on AppCode provides integration with GitHub which allows you to manage projects hosted on GitHub, fork external repositories, manage pull requests, and perform other GitHub operations from the IDE. See more details in the GitHub section.

From the main menu, select VCS | Import into Version Control | Share Project on GitHub. In the dialog that opens, enter your GitHub login and password and click Log In:

Github login

If you are not registered on GitHub, click Sign up for GitHub to go to and create a new account there. You can change the GitHub account or add a new one in Preferences | Version Control | GitHub. See more in Manage multiple accounts.
If you have two-factor authentication enabled for GitHub, the following dialog will appear:

GitHub authentication

Enter the code and click OK.

In the dialog that opens, you can change the repository name (by default, it is the same as the project name), the name of a remote (by default, origin), choose the repository type (public or private), and add some description if needed:

Create GitHub repo

Click Share. After the project is successfully published on GitHub, the following notification will appear:

GitHub notifications

You can edit the list of remotes in the Git Remotes dialog. To open the dialog, select VCS | Git | Remotes) from the main menu.

Step 5. Create a new branch

You may need to create a separate branch, for example, when you are working on an new feature and you don’t want your changes to get into the main (master) branch before they are tested.

Press ⌘T to pull the latest version of the current branch. On the status bar, you can see your current branch — master. Click it to open the Git Branches menu:

Git Branches menu

From the Git Branches menu, select New Branch. In the dialog that opens, specify the branch name, for example, new_feature, and select the Checkout branch checkbox to switch to the new branch right away:

Create new branch

If there are some unversioned changes in the current branch, you need to commit, revert, or shelve them before switching to another branch. See more in Switch between branches.

Now you are switched to the newly created branch:

Changed branch

Add the corresponding branch to the remote repository. To do this, select the local branch in the Git Branches menu and click Push. In the dialog that opens, click Push. The new branch will be added to the remote repository and will appear in the Remote Branches list in the Git Branches menu:

Remote branch

Step 6. Make and view the changes

Press ⌘T to pull the latest version of the current branch. Add a new file to the project, for example, SecondContentView.swift, and modify the ContentView.swift file.

In the Project tool window and in the editor tabs, AppCode applies different colors to files: blue to modified, green — to newly added. Moreover, in the gutter area of a modified file, the colored change markers appear next to the modified lines:

VCS gutter

Click the marker to view details:

VCS markers

Click Diff to view the difference in a separate window:

Separate Diff View

Go to the Local Changes tab of the Commit tool window ⌘K, to preview all the changes at once. Double-click a file to open the difference view in the editor:

Local Changes

See more in Review changes.

Step 7. Commit and push the changes

Press ⌘T to pull the latest version of the current branch. In the Commit tool window ⌘K, review the changes, make sure that the new file that you’re adding to Git is selected, type the commit message, and click Commit.

When typing the commit message, you can use auto-completion for the project file names ⌃Space:
Commit completion

Press ⇧⌘K or select VCS | Git | Push from the main menu to push the changes to the remote repository. The Push Commits dialog opens. Here you can see all the commits to be pushed as well as all the affected files. Before pushing the changes, you can see the differences for each file. To do this, right-click a file and select Show Diff or press ⌘D:

Show Diff

Click Push.

To undo the latest not pushed commit, right-click it on the Log tab of the Git tool window ⌘9 and select Undo Commit. For more details, go to Undo the last commit). To revert a pushed commit, right-click it on the Log tab of the Git tool window ⌘9 and select Revert commit. For more details, go to Revert a pushed commit.

Step 8. Merge branches and resolve conflicts

There are several ways how you can apply the changes from one branch to another, such as merging and rebasing the branches, cherry-picking commits, applying separate changes or files. All these methods are described in details in Apply changes from one Git branch to another.

In this tutorial, you will learn how to merge two branches and cherry-pick commits.

Merge branches

Select the master branch in the Git Branches menu on the status bar and click Checkout.

If there are some unversioned changes in the current branch, you need to commit, revert, or shelve them before switching to another branch. See more in Switch between branches.

Make some changes in ContentView.swift that has been modified before in the new_feature branch, for example:

Change in master

This way, we simulate a conflict situation. Push and commit the change as described above. From the Git Branches menu, select new_feature and click Merge into Current. Since we have made changes for the same file in different branches, the Conflicts dialog appears:

Conflicts view

Resolve conflicts

In the Conflicts dialog, you have several options to resolve the conflict:

  • Accept Yours: keep the changes made in the current branch.
  • Accept Theirs: apply the changes from the branch that you want to merge into the current one.
  • Merge: resolve conflicts manually in a dedicated dialog.

Click Merge. The Merge Revisions dialog opens:

Merge revisions

In this dialog, you can accept changes by clicking Apple left/Apply right, decline them by clicking Diff remove, and type code in the Result pane. See more in Resolve Git conflicts.

The syntax error are highlighted in the Merge Revisions window:

Merge Revisions

Resolve the conflict as on the screenshot above and click Apply.

Push the changes to the remote repository by pressing ⇧⌘K or selecting VCS | Git | Push from the main menu. You can see the commits in all the branches on Log tab of the Git tool window ⌘9:

Commits view

From here, you can also revert commits, cherry-pick changes from one branch to another, and more. See Log tab for more details.

Step 9. View history

In the master branch, open the ContentView.swift file. You see that the file’s syntax is broken — there are two containers within one view. Imagine these changes were made long ago or by someone else: you might be interested from which commit this code came. To find it out, do one of the following:

  • Right-click the file in the editor or in the Project tool window ⌘1 and select Git | Show History. The History tab of the Git tool window opens:Git HistoryOn this tab you can view all commits that affected the file and find out in which commit the change of your interest was added.
  • In the editor, select a code fragment you want to view history for, right-click the selection, and choose Git | Show History for Selection. The History for Selection window will open:History for selectionHere you can review all the commits that affected the code selection of your interest.

Find more ways of exploring the Git history in Investigate changes in Git repository.

Step 10. Cherry-pick commits

This operation allows you to apply changes from selected commits from one branch to another. In the master branch, fix the error in the ContentView.swift file, for example, by wrapping VStack and HStack in the List container. Commit ⌘K and push ⇧⌘K this change.

Switch to the new_feature branch. In the Git tool window ⌘9, open the Log tab. In the Branch list, select master. In the User list, select the user whose commits you want to see — me. Select your last commit and click Cherry pick:

Cherry Pick commits

Resolve the conflict by pressing Accept Theirs form the dialog that opens. This means we override the code in the ContentView.swift file by the changes from the cherry-picked commit. Commit the changes from the Commit Changes tool window that opens and push them ⇧⌘K.

If no conflicts emerge, the cherry-pick will be committed automatically, and you will just need to push the changes.

What’s next

If you didn’t find how to perform some specific Git task in this tutorial, refer to the Git guidelines — all the Git operations available from the IDE are described there.

For general information on working with version control systems, go to the Version control section. AppCode also supports Mercurial, Perforce, and Subversion.

If your project is not under version control, you can still track and manage local changes, roll back to the specific file state, restore deleted files, and more using the Local History feature.

Your AppCode team
The Drive to Develop