The pull command is the Git command that updates your local repository with remote changes. You can configure this command to operate in different ways, which vary depending on how you want to handle differences between your local and remote repositories, and whether you want to update both repositories with changes simultaneously. Frequently used pull configurations are:
- Fast-forwarding - Pulls remote changes to your local repository only, without making any remote changes. If remote changes conflict with local changes, the process aborts without making any modifications to either the local or the remote repository.
- Rebasing - Performs these sequential operations:
- Stores any local repository changes in a temporary stash.
- Pulls the remote repository changes and then updates the local repository with these remote changes.
- Tries to replay the stashed local repository changes on top of the newly updated files containing the remote changes. If none of the local and remote changes conflict with one another (by updating the same content in different ways), then the command successfully completes. In this case, your local repository has been updated with all remote changes, while leaving all local changes in place—you can now stage, commit, and push the local changes to the remote server. If, however, some of your local changes conflict with the remote changes, then Git modifies your local files to include the set of conflicting remote changes and adds merge markers around and between the local and remote changes. After marking all conflicts in all files, Git automatically pauses the rebasing process, and requires you to manually update each file containing conflicting changes to resolve all merge conflicts. After you have completed these manual modifications, Git completes the rebase procedure and leaves your repository ready to stage, commit, and push local changes to the remote server.
- Merging - While the previous two configurations only make local repository modifications, when using this configuration, pull simultaneously updates both the local and the remote repository to match one another by merging the changes from each. As with rebasing, if any merge conflicts occur, then Git marks all conflicts, and then stops the merge so that you can resolve the conflicts before continuing.
In the next section, we'll describe how to configure the pull command for the fast-forwarding configuration, which is generally the safest option (especially when you're new to version control) because it avoids making any remote modifications. Later, we'll look at how to handle conflicts between changes in your local repository and the remote repository.
Configuring local updates to fast-forward only
This section describes how to configure Git's pull command to update your local repository without making any remote modifications, and to abort the operation when a conflict would otherwise occur.
Note You only need to perform this command once; the configuration is then stored for all future repository operations performed using the current user account in the local repository.
To configure your local repository to make fast-forward changes only
- In your operating system, navigate to the top-level directory of the cloned Git repository on your local machine.
- Right-click the directory, and then click Git Bash Here on the shortcut menu.
- At the prompt, type the following command:
git config pull.ff only
You have now configured Git to perform local updates only when pulling remote changes, and to abort the update in the case of any merge conflicts.
Pulling remote changes
Now that you have configured the pull command, you are ready to use it to pull remote repository changes to your local repository. This section describes how to use the command and describes the different potential outcomes.
To pull remote changes to your local repository
- In your operating system, navigate to the top-level directory of the cloned Git repository on your local machine.
- Right-click the directory, and then click Git Bash Here on the shortcut menu.
- At the prompt, type the following command:
git pull
Depending on what changes exist in the remote repository, you'll see one of the following outcomes:
- If no new changes exist:
If no new changes exist in the remote repository, then the command returns a message indicating that the local repository is already up to date with the remote repository. In this case, you are now ready to stage, commit, and push any local changes to the remote repository.
- If remote changes are retrieved:
If new changes are available in the repository, and none of those changes conflict with local changes, then the command updates the local repository and returns a message indicating what new or modified content was retrieved from the remote repository. Similar to when no new remote changes exist, you are now ready to stage, commit, and push any local changes to the remote repository.
- If a merge conflict occurs:
If the remote repository includes changes to the same sections of any of the same files that you have modified locally, then the command aborts with an error, and no changes are made to either the local or the remote repository. In this case, updating your local repository requires you to rebase your local repository and resolve any merge conflicts or perform a simultaneous merge of both local and remote changes (this latter option is not described in this documentation).