Difference between revisions of "Git 101"
Line 123: | Line 123: | ||
$ git commit -m 'Added <newfile>" | $ git commit -m 'Added <newfile>" | ||
* To commit | * To commit changes to an existing file: | ||
$ git add <modifiedfile> | $ git add <modifiedfile> | ||
$ git commit -m 'Updated <modifiedfile>" | $ git commit -m 'Updated <modifiedfile>" |
Revision as of 21:32, 21 November 2023
Git Workflow Components
- Working Directory: Your local workspace where you edit files. Changes here are not tracked until moved to the staging area.
- Staging Area: A prep zone for changes to be committed. You can selectively choose which changes to include in a commit.
- HEAD: The latest commit in the current branch, acting as a pointer to your most recent work.
- Local Repository: Your computer's storage for all your commits, branches, and the entire change history. It operates independently of network access.
- Remote Repository: A server-hosted repository (e.g., GitLab, GitHub) for code sharing and backup. It syncs with the local repository through
push
andpull
commands.
Note: For the longest time, the default branch in most Git repositories was named master
; the convention is now to name is main
. To rename the local master
branch:
$ git branch -m master main
To rename the remote master
branch, see here.
Git File Status
Tracked vs Untracked Files
- Tracked files are those that Git knows about and has in its version history.
- Untracked files are new or unrecorded files in your working directory that Git isn't keeping track of yet; e.g.
temp/
,auto_settings.sav*
,auto_positions.sav*
, etc.
Staged vs Unstaged
- Staged files are those that have been marked for inclusion in the next commit, showing Git exactly what changes you want to commit.
- Unstaged files are the modified files in your working directory that have not been marked for the next commit yet.
Git add
The git add
command is used for both staging changes and beginning to track new files:
- Staging Changes: When you modify a file that is already being tracked by Git (i.e., it's been committed at least once before), using
git add <filename>
stages these changes. This means you're marking the modifications in that file to be included in the next commit. - Tracking New Files: For new files that are not yet tracked by Git (they have never been committed),
git add <filename>
starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.
Why stage?
- What is Staging? Staging in Git is the process of selecting specific changes you want to include in your next commit. Instead of committing all the changes you've made since the last commit, you can choose a subset of these changes to commit.
- What are Atomic Commits? Atomic commits refer to the practice of making each commit a self-contained unit of change that can stand on its own, making the code history more understandable and easier to navigate.
Basic Commands
Viewing Changes and Status
- To see the status of the working directory and staging area:
$ git status
- To list the commit history:
$ git log
- To view differences since the last commit:
$ git diff <file>
- To see tracked files:
$ git ls-files
Committing Changes
- To commit a single tracked file (file to staging area and commit changes in two steps):
$ git add <file> $ git commit -m 'commit message'
- To commit all tracked files at once, use option
-a
(add to staging area and commit in a single step):
$ git commit -am 'commit message'
Ignoring Files
.gitignore
lists files and folders to be ignored. To update the list, just use any file editor.
Syncing with Remote Repository
- To download updates from the remote repository without merging them:
$ git fetch
- To fetch changes from the remote repository and merge them into your current branch:
$ git pull
- To push local commits to the remote repository:
$ git push # pushes your commits to the remote repository
- To view the remote repository information:
$ git remote -v # lists the remote repositories and their URLs
Git Fetch vs. Git Pull
git fetch
is a command that downloads changes from a remote repository, but doesn't integrate any of these changes into your working files. It's essentially a safe way to review changes before integrating them into your local repository.git pull
is a command that not only downloads changes from the remote repository but also immediately attempts to merge them into the branch you are currently working on. It is a combination ofgit fetch
followed bygit merge
.
Practical Step-by-Step Examples
Basic Workflow
This workflow assumes you are working with the main
branch:
- To sync your local repository with the remote repository:
$ git checkout main # Make sure your are on the main branch $ git pull # Pull the latest changes from the remote
- To commit new files:
$ git add <newfile> $ git commit -m 'Added <newfile>"
- To commit changes to an existing file:
$ git add <modifiedfile> $ git commit -m 'Updated <modifiedfile>"
- To commit all changes:
$ git commit -am 'Description of changes'
- To push your changes to the remote repository:
$ git push
Version control for EPICS IOCs
Initialize the local repository:
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from xxx $ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from xxx $ git init # initialize repo $ git add . # stage all relevant stuff $ git status # confirm status $ git commit -m 'first commit yeah!' # commit all staged files
On GitLab, in the corresponding beamline group:
- New project (blue button, upper right corner)
- Create blank project
- Project name: myioc (same spelling as IOC prefix)
- Project slug: myioc (needs to be the same as project name)
- Visibility Level: Internal
- Project Configuration: Uncheck initialize repository (very important to avoid conflict between local and remote)
- Create project
- Clone drop-down (blue button, right hand-side): copy
ssh [email protected]:29id/myioc.git
Back to the local repository, add the reference to the new remote repository:
$ git remote add origin [email protected]:29id/myioc.git # adds a new remote repository named origin with the given URL) $ git remote -v # lists remote connections to confirm the addition $ git push -u origin main # pushes main to the origin remote and sets origin/main as the upstream for your local main branch
Note: The -u
flag stands for --set-upstream
. This flag is used to set a relationship between your local branch and a remote branch: origin/main
is now the upstream for your current local branch. This means the next time you want to push to main on origin, you can just type git push
instead of git push
origin main (same goes with git pull
)
Branching for EPICS IOCs upgrade
- Make sure your local repository in
synApps_6_1
is up-to-date:
$ git checkout main # Make sure your are on the main branch $ git fetch # Fetch the latest changes from the remote $ git pull # Pull (fetch + merge) the latest changes from the remote
- Create and switch to a new branch named
synApps_6_1
(for archive purposes)
$ git checkout -b synApps_6_1 # Create a new branch based on main and switch to it $ git push -u origin synApps_6_1 # Push the new branch to the remote and set it as the upstream
- Clone the IOC repository into the
synApps_6_2_1
directory:
$ cd ../../../synApps_6_2_1/ioc/ # Navigate to the synApps_6_2_1/ioc directory $ git clone [email protected]:29id/myioc.git # Clone the repository
- Note:
- In the directory
synApps_6_1/ioc/myioc
, you will be working on thesynApps_6_1
branch. - In the directory
synApps_6_2_1/ioc/myioc
, you will be working on themain
branch.
- In the directory
Git Status Explained
General Case
$ git status On branch main Your branch is up to date with 'origin/main'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) modified: file1 new file: file2 Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: file3 Untracked files: (use "git add <file>..." to include in what will be committed) temp/ notes.txt
- On Branch: You're currently on the
main
branch. - Branch Status: Your
main
branch is up to date withorigin/main
(the main branch from the remote repository). - Changes to be Committed:
file1
has been modified andfile2
is a new file, both staged for the next commit.- To unstage, use
git reset HEAD <file>
.
- Changes Not Staged for Commit:
file3
is modified but not staged.- To stage, use
git add <file>
. - To discard changes, use
git checkout -- <file>
.
- Untracked Files:
temp/
andnotes.txt
are not tracked by Git.- To track, use
git add <file>
. - To ignore, add them to the
.gitignore
file
Your branch is ahead of 'origin/main'
$ git status On branch main Your branch is ahead of 'origin/main' by 3 commits. (use "git push" to publish your local commits) nothing to commit, working tree clean
- On Branch: You're currently on the
main
branch. - Branch Status:
- Your
main
branch is ahead oforigin/main
by 3 commits. This means you have made commits locally that are not yet in themain
branch on the remote repository. - To synchronize these changes with the remote repository, use
git push
.
- Your
- Working Tree Status:
- Your working directory is clean, meaning there are no unstaged changes or untracked files.
Your branch is behind 'origin/main'
$ git status On branch main Your branch is behind 'origin/main' by 2 commits, and can be fast-forwarded. (use "git pull" to update your local branch) nothing to commit, working tree clean
- On Branch: You're currently on the
main
branch. - Branch Status:
- Your
main
branch is behindorigin/main
by 2 commits. This indicates that there are updates on the remote repository that you don't have locally. - You can fast-forward your local branch to catch up with
origin/main
usinggit pull
.
- Your
- Working Tree Status:
- Your working directory is clean, meaning there are no unstaged changes or untracked files.
Your branch and 'origin/main' have diverged
$ git status On branch main Your branch and 'origin/main' have diverged, and have 1 and 2 different commits each, respectively. (use "git pull" to merge the remote branch into yours) You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge) Unmerged paths: (use "git add <file>..." to mark resolution) both modified: conflicted_file.txt no changes added to commit (use "git add" and/or "git commit -a")
- On Branch: You're currently on the
main
branch. - Branch Divergence:
- Your local
main
branch and remoteorigin/main
branch have diverged. This means there are different commits in both branches that are not in the other.
- Your local
- Merge Conflict:
- A merge conflict has occurred in
conflicted_file.txt
due to differing changes from both the local and remote branches. - To resolve the merge conflict, manually edit the file to reconcile the differences, then use
git add <file>
to mark the conflict as resolved. - After resolving the conflict, complete the merge by committing the changes with
git commit
. - If you wish to cancel the merge, use
git merge --abort
.
- A merge conflict has occurred in
- Working Tree Status:
- Address the merge conflict before proceeding with other Git operations.
- More info here.
Branching Basics
Overview
- What is a Branch?
It's essentially a separate line of development. You can think of it as an independent line of work that doesn't interfere with others.
- Why Use Branches?
They allow you to work on new features, bug fixes, or experiments in isolation from the main (deployed) code. Branches facilitate parallel development, enabling multiple team members to work on different aspects simultaneously without stepping on each other's toes.
- How Does it Work?:
When you create a branch in Git, you're creating a new pointer to commits. It's like a bookmark on your work, allowing you to switch contexts quickly. Changes made in a branch don't affect other branches. You can merge these changes back into the main branch when they're ready.
Typical Workflow
- Create a new branch from the
main
branch:
$ git checkout main # Switch to the main branch $ git pull # Ensure it's up to date with the remote $ git checkout -b new-branch # Create and switch to a new branch
- Make your changes in this new branch and test them to ensure they work as intended.
- Add and commit your changes:
$ git add <modifiedfile> $ git commit -m "Your commit message"
- Merge the branch back into
main
once your work is complete:
$ git checkout main # Switch back to the main branch $ git pull # Update the main branch (just in case) $ git merge new-branch # Merge the new branch into main $ git push # Push the updates to the remote repository
This workflow assumes you're starting from and merging back into a branch named main
. Replace main with the appropriate branch name if different in your repository.