Beam Line Controls - User contributions [en]

Git 101

2024-08-08T18:16:02Z

Rodolakis: /* GitLab */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* It is recommended to use an organization vs individual account to host shared project (e.g. beamline software).
* The naming convention recommended for a given beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)
* BCDA organization: https://github.com/BCDA-APS

===== GitLab =====

GitLab is typically used for internal project (e.g. IOCs, UI screens...). APS hosts its own GitLab service: https://git.aps.anl.gov. Contact your IT contact to get access.
* GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:14:35Z

Rodolakis: /* GitHub vs GitLab: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* It is recommended to use an organization vs individual account to host shared project (e.g. beamline software).
* The naming convention recommended for a given beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)
* BCDA organization: https://github.com/BCDA-APS

===== GitLab =====

GitLab is typically used for internal project (e.g. IOCs, UI screens...). APS hosts its own GitLab service: https://git.aps.anl.gov. Contact your IT contact to get access.
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:10:55Z

Rodolakis: /* GitHub vs GitLab: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* It is recommended to use an organization vs individual account to host shared project (e.g. beamline software).
* The naming convention recommended for a given beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)
* BCDA organization: https://github.com/BCDA-APS

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:10:34Z

Rodolakis: /* GitHub */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* It is recommended to use an organization vs individual account to host shared project (e.g. beamline software).
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)
* BCDA organization: https://github.com/BCDA-APS

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:09:45Z

Rodolakis: /* GitHub vs GitLab: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)
* BCDA organization: https://github.com/BCDA-APS

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:09:15Z

Rodolakis: /* GitHub vs GitLab: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (i.e. your own GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* BCDA organization: https://github.com/BCDA-APS
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:08:58Z

Rodolakis: /* GitHub */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (*your* GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* BCDA organization: https://github.com/BCDA-APS
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:08:47Z

Rodolakis: /* GitHub */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (**your** GitHub account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* BCDA organization: https://github.com/BCDA-APS
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:07:49Z

Rodolakis: /* GitHub */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (your github account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* BCDA organization: https://github.com/BCDA-APS
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:07:13Z

Rodolakis: /* Putting a new project/folder under version control */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

===== GitHub =====

GitHub https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
* GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (your github account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
* BCDA organization: https://github.com/BCDA-APS
* It is recommended to use an organization vs individual account to host shared project.
* The naming convention recommended for the beamline organization is: APS-SSS-GGG
** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
** GGG: operating group (e.g. MM for XSD - Magnetic Material)

===== GitLab =====

APS's GitLab (https://git.aps.anl.gov) is typically used for internal project (e.g. IOCs, UI screens...)
* APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
* BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
* It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T18:05:37Z

Rodolakis: /* GitLab vs GitHub: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitHub vs GitLab: What should I use? ====

* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
** GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account (your github account) or a named organization (e.g. BCDA-APS or APS-29IDC-MM).
** BCDA organization: https://github.com/BCDA-APS
** It is recommended to use an organization vs individual account to host shared project.
** The naming convention recommended for the beamline organization is: APS-SSS-GGG
*** SSS: sector, beamline, and station, if relevant (e.g. 29IDC)
*** GGG: operating group (e.g. MM for XSD - Magnetic Material)

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
** APS GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
** BCDA maintains group for each beamline; ask your BCDA contact to be added to your beamline group.
** It is recommended to use your beamline group vs individual account to host shared project (individual accounts are deleted when employee leave the lab).

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T17:54:42Z

Rodolakis: /* GitLab vs GitHub: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitLab vs GitHub: What should I use? ====

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
** GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
** BCDA maintains group for each beamline; ask your beamline contact to be added to your beamline group.
* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
** GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY, where "ORGANIZATION" is either a single user account or a named organization.
** BCDA organization: https://github.com/BCDA-APS

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T17:54:27Z

Rodolakis: /* GitLab vs GitHub: What should I use? */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitLab vs GitHub: What should I use? ====

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
** GitLab organizes repositories using this pattern: https://git.aps.anl.gov/GROUP/REPOSITORY
** BCDA maintains group for each beamline; ask your beamline contact to be added to your beamline group.
* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
** GitHub organizes repositories using this pattern: https://github.com/ORGANIZATION/REPOSITORY
where "ORGANIZATION" is either a single user account or a named organization.
** BCDA organization: https://github.com/BCDA-APS

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T16:06:31Z

Rodolakis: /* GitLab vs GitHub */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitLab vs GitHub: What should I use? ====

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
* BCDA maintains sector "groups"
* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
* Note that BCDA has his own "organization" on GitHub: https://github.com/BCDA-APS

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T16:05:17Z

Rodolakis: /* Putting a new project/folder under version control */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

==== GitLab vs GitHub ====

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
* BCDA maintains sector "groups"
* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
* BCDA has his own organization on GitHub: https://github.com/BCDA-APS

==== Example on GitLab ====

This section uses the example of an EPICS IOCs, i.e. GitLab (steps are the same on GitHub). For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-08-08T16:02:27Z

Rodolakis: /* Putting a new project/folder under version control */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

GitLab vs GitHub - best practices:

* GitLab: https://git.aps.anl.gov is typically used for internal project (e.g. IOCs, UI screens...)
* BCDA maintains sector "groups"
* GitHub: https://github.com is typically used for public project, to be shared accros user facilities or with the users themselves (e.g. apstools, MDA_Utilities...)
* BCDA has his own organization on GitHub: https://github.com/BCDA-APS

This section uses the example of an EPICS IOCs. For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-02-18T15:24:44Z

Rodolakis: /* Putting a new folder under version control */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new project/folder under version control ===

This section uses the example of an EPICS IOCs. For a different type of project, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-02-18T15:24:08Z

Rodolakis: /* Version Control for EPICS IOCs */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Putting a new folder under version control ===

THis use the example of an EPICS IOCs. For a different project/folder, just skip the reference to `xxx` (first 2 lines in the repo initialization).

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Beamline Controls

2024-02-01T00:34:27Z

Rodolakis: /* Getting Started */

WIKI for the APS Beamline Controls Community, maintained by the Beamline Controls Technical Working Group. 
This wiki exists to collect the output of the working group, including documentation on beamline controls software and hardware useful for APS beamline scientists and resident users.

----

===Getting Started===
* [[EPICS Cheat Sheet]]: Channel Access command-lines, noteworthy record fields & IOC shell commands.
* [[EPICS 101]]: definition of basic EPICS components ([[EPICS_101#What_is_an_IOC.3F|IOC]], [[EPICS 101#What_is_a_PV.3F|PV]], [[EPICS_101#What_is_a_record.3F|record]], [[EPICS 101#What_is_a_database.3F|database]]).
* [[IOC 101]]: learn how to create your own IOC.
* [[Git_101|Git 101]]: git refresher (basic workflow, commands, and more).

===Beamline Controls Documentation===

* [[EPICS networking]]: basic overview of how to control the network paths used by EPICS IOCs and clients.
* [[Controls Software Documentation]]
* [[Hardware and IT Configuration]]

===Practical Beamline Controls Training (2023)===

[[Practical_Beamline_Controls_Training#IOC_Basics|Session 1: IOC Basics]]
[[Practical_Beamline_Controls_Training#IOC_Deployment_.26_Troubleshooting|Session 2: IOC Deployment & Troubleshooting]]

===Beamline Controls Technical Working Group information===

The BC Technical Working (BCTWG) group meets monthly to review and gather feedback on possible changes in either the way BC delivers support or the technologies that BC supports. The BCTWG comprises the BC group plus interested stakeholders from XSD. In a nutshell, the main goal of the BCTWG is to improve communication between BC and its customers on topics of mutual interest.

* Box folder with slides and meeting notes (ANL only): [https://anl.box.com/s/chcn7xauil93inay8ipinbxtcckc9k9f]

* Current chairs:
** Kevin Peterson (XSD-BC)
** Tejas Guruswamy (XSD-DET)
** Andrew Chuang (XSD-MPE)

===Beamline Data Pipelines===

* https://git.aps.anl.gov/groups/bdp-public/-/wikis/home

Beamline Controls

2024-02-01T00:34:15Z

Rodolakis: /* Getting Started */

WIKI for the APS Beamline Controls Community, maintained by the Beamline Controls Technical Working Group. 
This wiki exists to collect the output of the working group, including documentation on beamline controls software and hardware useful for APS beamline scientists and resident users.

----

===Getting Started===
* [[EPICS Cheat Sheet]]: Channel Access command-lines, noteworthy record fields & IOC shell commands.
* [[EPICS 101]]: definition of basic EPICS components ([[EPICS_101#What_is_an_IOC.3F|IOC]], [[EPICS 101#What_is_a_PV.3F|PV]], [[EPICS_101#What_is_a_record.3F|record]], [[EPICS 101#What_is_a_database.3F|database]]).
* [[IOC 101]]: learn how to create your own IOC.
* [[Git_101|Git 101]]: git refresher (basic workflow, commands, and more)

===Beamline Controls Documentation===

* [[EPICS networking]]: basic overview of how to control the network paths used by EPICS IOCs and clients.
* [[Controls Software Documentation]]
* [[Hardware and IT Configuration]]

===Practical Beamline Controls Training (2023)===

[[Practical_Beamline_Controls_Training#IOC_Basics|Session 1: IOC Basics]]
[[Practical_Beamline_Controls_Training#IOC_Deployment_.26_Troubleshooting|Session 2: IOC Deployment & Troubleshooting]]

===Beamline Controls Technical Working Group information===

The BC Technical Working (BCTWG) group meets monthly to review and gather feedback on possible changes in either the way BC delivers support or the technologies that BC supports. The BCTWG comprises the BC group plus interested stakeholders from XSD. In a nutshell, the main goal of the BCTWG is to improve communication between BC and its customers on topics of mutual interest.

* Box folder with slides and meeting notes (ANL only): [https://anl.box.com/s/chcn7xauil93inay8ipinbxtcckc9k9f]

* Current chairs:
** Kevin Peterson (XSD-BC)
** Tejas Guruswamy (XSD-DET)
** Andrew Chuang (XSD-MPE)

===Beamline Data Pipelines===

* https://git.aps.anl.gov/groups/bdp-public/-/wikis/home

Beamline Controls

2024-02-01T00:33:40Z

Rodolakis:

WIKI for the APS Beamline Controls Community, maintained by the Beamline Controls Technical Working Group. 
This wiki exists to collect the output of the working group, including documentation on beamline controls software and hardware useful for APS beamline scientists and resident users.

----

===Getting Started===
* [[EPICS Cheat Sheet]]: Channel Access command-lines, noteworthy record fields & IOC shell commands.
* [[EPICS 101]]: definition of basic EPICS components ([[EPICS_101#What_is_an_IOC.3F|IOC]], [[EPICS 101#What_is_a_PV.3F|PV]], [[EPICS_101#What_is_a_record.3F|record]], [[EPICS 101#What_is_a_database.3F|database]]).
* [[IOC 101]]: learn how to create your own IOC.
* [[Git_101|Git 101]]

===Beamline Controls Documentation===

* [[EPICS networking]]: basic overview of how to control the network paths used by EPICS IOCs and clients.
* [[Controls Software Documentation]]
* [[Hardware and IT Configuration]]

===Practical Beamline Controls Training (2023)===

[[Practical_Beamline_Controls_Training#IOC_Basics|Session 1: IOC Basics]]
[[Practical_Beamline_Controls_Training#IOC_Deployment_.26_Troubleshooting|Session 2: IOC Deployment & Troubleshooting]]

===Beamline Controls Technical Working Group information===

The BC Technical Working (BCTWG) group meets monthly to review and gather feedback on possible changes in either the way BC delivers support or the technologies that BC supports. The BCTWG comprises the BC group plus interested stakeholders from XSD. In a nutshell, the main goal of the BCTWG is to improve communication between BC and its customers on topics of mutual interest.

* Box folder with slides and meeting notes (ANL only): [https://anl.box.com/s/chcn7xauil93inay8ipinbxtcckc9k9f]

* Current chairs:
** Kevin Peterson (XSD-BC)
** Tejas Guruswamy (XSD-DET)
** Andrew Chuang (XSD-MPE)

===Beamline Data Pipelines===

* https://git.aps.anl.gov/groups/bdp-public/-/wikis/home

Git 101

2024-02-01T00:31:01Z

Rodolakis: /* Version Control for EPICS IOCs */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see [[#Why clone with SSH URL|Why clone with SSH URL]].

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-02-01T00:26:59Z

Rodolakis: /* Version Control for EPICS IOCs */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>
Note: see Why clone with SSH URL

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-02-01T00:25:38Z

Rodolakis: /* Upstream Branch */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Choosing a URL for your remote repository ===

==== Why clone with SSH URL ====

Github support for password authentication (HTTPS) was removed on August 13, 2021. SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account add the public key to your account on GitHub.com]

If you cloned your repository using the HTTP URL, you can switch to SSH at any time:

git remote -v # check the current repo url
origin https://github.com/BCDA-APS/myrepo (fetch)
origin https://github.com/BCDA-APS/myrepo (push)
git remote set-url origin git@github.com:BCDA-APS/myrepo.git
git remote -v # verify the changes to the new url
origin git@github.com:BCDA-APS/myrepo.git (fetch)
origin git@github.com:BCDA-APS/myrepo.git (push)

==== More details about HHTPS vs SSH ====

* HTTPS (Hypertext Transfer Protocol Secure):
** Ease of Use: Generally easier for beginners to set up and use, as it often works out of the box without any additional configuration.
** Authentication: Uses username and password for authentication. This can be less convenient because you might need to enter your credentials frequently unless you use a credential helper.
** Security: Secure, as it encrypts the data transferred over the network.

* SSH (Secure Shell):
** Ease of Use: Requires a bit more setup initially. You need to generate an SSH key pair and add the public key to your GitHub account.
** Authentication: Uses key-based authentication. This is more secure and convenient once set up, as you don’t have to enter your username and password regularly.
** Security: Highly secure, with strong encryption of data. The key-based authentication is generally considered more robust than password-based authentication.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-01-19T00:38:16Z

Rodolakis: /* Version Control for EPICS IOCs */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Code drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2024-01-18T23:06:17Z

Rodolakis: /* Branching for IOCs Upgrade */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

This is an example for upgrading from 6.1 to 6.2:

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-20T00:51:45Z

Rodolakis: /* Custom aliases */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png|thumb|center|900px]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-20T00:51:18Z

Rodolakis: /* Custom aliases */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits:

[[File:git_lg.png]]

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

File:Git lg.png

2023-12-20T00:50:17Z

Rodolakis:

IOC 101

2023-12-08T22:54:34Z

Rodolakis: /* What's next? */

== What is an IOC ==

For a basic description, see [https://wiki-ext.aps.anl.gov/blc/index.php?title=EPICS_101#What_is_an_IOC.3F Epics 101]
[[File:EPICS_basics_PV_diagram.png|right|thumb|700px]]

 
== How does one create an IOC? ==

There are multiple ways to create an IOC, but no one does it from scratch:

=== The EPICS base approach ===

Not recommended: it creates a bare bones IOC but requires more knowledge of the EPICS build system to get started:
::'''<code>makeBaseApp.pl</code>'''
* Must be run multiple times
* Creates IOC contents in the current directory
* synApps support needs to be added manually

=== The synApps approach ===

It is based on the ''xxx'' module and designed to give you a usable IOC with as little effort as possible:
:::'''<code>/APSshare/bin/mkioc</code>'''

* A single command leaves you with an IOC you can build:

$/APSshare/bin/mkioc -n -f -s 6-2-1 kmp

Usage: mkioc [options] ioc_name
-h print this message
-v print the version
-f create a fresh git repo without an xxx remote
-g default to creating gitlab repo and pushing ioc
-n default to not creating gitlab repo and pushing ioc
-s <version> use a specific synApps version

* Creates a top-level IOC directory in the current directory
* Common synApps support is included by default (common records/modules such as '''alive''', '''sscan''', '''calc'''...)
* '''<code>mkioc</code>''' will ask you questions if you run it without options

Note: The BCDA convention is to name development IOCs using the developer's initials (here we will use either ''xxx'' or ''kmp'').

 

== IOC Layout ==

=== Overview ===

The IOC layout can be overwhelming and confusing to those who aren’t yet familiar with it. The EPICS build system creates many directories, making it harder to find the important directories.
Important files are often buried multiple directories down from the top-level. It is helpful to look at subsets of the IOC directory.

 
Note:
* '''build''': building an IOC is the action of compiling i.e. generating the binary <code>bin/rhel#-x86_64/xxxApp</code> (plus other build products as described below) by using the command '''<code>make</code>'''.
* '''run''': running an IOC is the action of running the binary along with a startup script of iocsh commands (usually called '''<code>st.cmd</code>''')

 
Note:
* Any change in the build configuration ('''Orange folders''') requires to recompile the IOC by issuing a '''<code>make</code>'''.
* Any change in the runtime configuration ('''Green folders''') requires to reboot the IOC.

[[File:IOCtree.jpg|right|thumb|300px|xxx IOC tree]]

=== Build configuration ===

'''Orange folders:'''
* '''<code>xxx/configure</code>''':
:contains the files that specify which versions of EPICS base and EPICS modules should be used when building the IOC.
* '''<code>xxx/xxxApp/Db</code>''':
:contains local databases (and associated autosave files) and protocol files used by the IOC.
* '''<code>xxx/xxxApp/src</code>''':
:contains the Makefile that determines all of the software that gets built into the IOC binary. ; local sequence programs and other EPICS support that needs to be compiled go here.

=== Intermediate build directories ===

'''Grey folders: ''' The EPICS build system will generate '''<code>O.</code>''' files (Common, EPICS HOST and TARGET architectures) in the configure, Db, and src directories (orange directories). These directories are not needed after the IOC is built and can be removed with the '''<code>make clean</code>''' command. If they are not removed, they can be safely ignored. It is highly unlikely that you will ever need to look at any of the files in them.

=== Build products ===

'''Red folders:''' 
The EPICS build system creates top level bin, db, dbd, and lib directories:
* '''<code>xxx/bin/rehl8-x86_64</code>''':
:contains the architecture-specific IOC binary (or munch file for VxWorks IOCs).
* '''<code>xxx/db</code>''':
:contains installed database files which may or may not be used, since many IOCs reference the databases in the '''<code>Db</code>''' directory instead.
* '''<code>xxx/dbd</code>''':
:contains a single database definition file to be loaded by the IOC.
* '''<code>xxx/lib/rehl8-x86_64</code>''':
:contains architecture-specific files for EPICS modules, but should be empty for the IOC. 
The build system creates an '''<code>envPaths</code>''' file in the startup directory '''<code>iocBoot/iocxxx</code>''', which contains the locations of the modules defined in the '''<code>RELEASE</code>''' file.

=== Startup directory ===

'''Green folders:''' 
The '''<code>iocxxx</code>''' directory is referred to as the '''startup''' directory. It contains the '''<code>st.cmd</code>''' file, which is the '''runtime configuration''' for the IOC (i.e. all the files the IOC needs to load to run/start).
The IOC’s config is often broken into separate '''<code>.iocsh</code>''' (or '''<code>.cmd</code>''') files so that support can be more easily commented out and to improve readability; '''<code>substitutions</code>''' and '''<code>iocsh</code>''' files usually reside in subdirectories to reduce clutter in the startup directory.

=== Startup scripts ===

'''Blue folders:''' 
The top-level IOC directory '''<code>xxx</code>''' contains scripts that start medm & caQtDM.
The startup directory <code>'''softioc'''</code> subdirectory contains a bash script which simplifies managing the IOC on Linux.
Windows IOCs: the startup directory contains batch files to start the IOC.

Note: The startup directory can reside elsewhere.

 

== How does support get into an IOC? ==

=== Quick overview ===

[[File:EPICS_basics_linking_diagrams.png|right|thumb|800px]]
* '''<code>configure/RELEASE</code>''':
** Defines the locations of EPICS base and EPICS modules
** Often includes other RELEASE files
** '''Note: already included when using <code>mkioc</code>'''
* '''<code>xxxApp/src/Makefile</code>''':
** Specifies which database definitions ('''<code>dbd</code>''') to include
** Specifies which libraries should be included in the IOC binary
** Specifies which local code should be included in the IOC binary
** Libraries will not be included unless an associated '''<code>dbd</code>''' file is included
** The order of the libraries is important (single-pass linker)
** '''Note: unless you are adding a non-synApps module or an uncommon motor driver, you should not need to modify the <code>Makefile</code>'''
* '''<code>iocBoot/iocxxx/st.cmd</code>''':
** That is the runtime configuration file, i.e. the primary IOC config file that is sourced when the IOC is started: determines all the things that gets loaded (e.g. ''I want 7 motor records, with these names, and this resolution, etc...'')
** Name can vary slightly based on how the IOC was created
** '''Note: this is the file that you will very likely modify'''
 

=== Startup script <code>st.cmd</code> ===

Legacy IOCs often have monolithic '''<code>st.cmd</code>''' files. Newer IOCs source more '''<code>.iocsh</code>''' files from EPICS modules, which makes it easier to keep an IOC's config up-to-date.

< envPaths

dbLoadDatabase("../../dbd/iocxxxLinux.dbd")
iocxxxLinux_registerRecordDeviceDriver(pdbbase)

### Databases are loaded
### Drivers are initialized/configured here

iocInit

### Sequence programs & autosave are started here

dbl > dbl-all.txt

date

We can break it up into 3 functional zones:
* '''Zone 1''' - before '''<code>dbLoadDatabase</code>''': it is usually dedicated to setting-up the environment (e.g. defines environment variables and paths to EPICS modules).
* '''Zone 2''' - after '''<code>dbLoadDatabase</code>''' & before '''<code>iocInit</code>''': this is were most of the software is loaded (e.g. databases and substitutions template are loaded here, drivers are initialized and configured).
* '''Zone 3''' - after '''<code>iocInit</code>''': this zone is mostly empty thanks to '''<code>doAfterIocInit</code>''' from the '''<code>std</code>''' module (sequence programs and autosave get initialized here, but the calls that do the initializing appear much earlier in the startup)

Note: PVs are available during '''<code>iocInit</code>''', even though the IOC is still starting up.
 

=== Autosave ===

'''autosave''' is a synApps module that provides seamless reboot functionality. It is mostly automatic when '''<code>mkioc</code>''' is used.
PVs are saved while the IOC is running and loaded during '''<code>iocInit</code>'''.
Autosaved values overwrite database defaults.

[[File:IOC_autosave.jpg|right|thumb|300px]]

In ''xxx''-based IOCs, created using '''<code>mkioc</code>''', autosave is included by default: '''<code>common.iocsh</code>''' contains all the necessary configuration, and you will only need to modify it if you want to customize something. It also includes an '''autosaveBuild''' feature: every loaded database with associated req files ('''<code>_settings.req</code>''') are automatically added to '''<code>autosave/built_position.req</code>''' and '''<code>autosave/built_settings.req</code>''', so long as they use the correct naming convention, i.e. the '''<code>_settings.req</code>''' uses the same prefix as the database. 
The legacy request files, '''<code>autosave_position.req</code>''' and '''<code>autosave_settings.req</code>''' (that live outside the '''<code>autosave</code>''' directory) are reserved for things added manually (often empty).
Multiple '''<code>.sav</code>''' files can be created:
* Default:
** '''<code>.sav</code>''' & '''<code>.savB</code>'''
** actually restored when the IOC restarts
* Periodic:
** '''<code>.sav0</code>''', '''<code>.sav1</code>''', '''<code>.sav2</code>''', …
** overwritten cyclically; if the default one do not exist, those ones get restored.
* Dated:
** '''<code>.sav-230109-134502</code>'''
** written once at boot time

The 1st half of '''<code>common.iocsh</code>''' sets up autosave:
[https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46 https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46]
 

=== How to build & clean a Linux IOC ===

* Confirm the RHEL version
** <code> '''uname -r''' → 3.10.0-1160.62.1.'''el7'''.x86_64</code>
** <code> '''cat /etc/redhat-release''' → Red Hat Enterprise Linux Server release '''7.9'''</code>
* Set <code> EPICS_HOST_ARCH</code> environment variable
** bash: <code>'''export EPICS_HOST_ARCH=rhel7-x86_64'''</code>
** tcsh: <code>'''setenv EPICS_HOST_ARCH rhel7-x86_64'''</code>
* Initiate the build in the top-level IOC directory:
** <code>'''make'''</code>

* Remove intermediate build dirs (for the current <code> EPICS_HOST_ARCH</code>):
** <code>'''make clean'''</code>
* Remove all intermediate build dirs and top-level build directories to start fresh:
** <code>'''make distclean'''</code>
* Show all make options:
** <code>'''make help'''</code>

== Running an IOC ==
 

=== Use the script ===
 
==== Create an alias ====

Create an alias for the script (assuming PWD = IOC’s top-level dir)
:<code>$ '''alias kmp=${PWD}/iocBoot/iockmp/softioc/kmp.sh'''</code>
:<code>$ '''kmp''' </code>
:<code>Usage: kmp.sh {console|restart|run|start|caqtdm|medm|status|stop|usage}</code>

Noteworthy arguments:
* '''<code>run</code>''': Runs the IOC in the current terminal (doesn't return the command prompt). Useful for troubleshooting. Problematic for normal operation.
* '''<code>start</code>''': Runs the IOC in the background (returns the command prompt) using screen or procServ.
* '''<code>status</code>''': Tells you if the IOC is running and refuses to start if it is.

Note:
* Use the full path to the IOC’s start script so the alias can be run from any directory (bash syntax shown).
* <code>EPICS_HOST_ARCH</code> needs to still be set otherwise the IOC will not start (unless the <code>EPICS_HOST_ARCH</code> is hard-coded in the start script).

==== Start caQtDM ====

:'''<code>kmp caqtdm &</code>'''

Note: the ampersand is needed for synApps_6_2_1 IOCs, but it won’t be needed in the future because it was added to the '''<code>start_caQtDM_xxx</code>''' script.

==== Start the IOC ====

Starts the IOC in the background (using screen or procServ):

:'''<code>kmp start</code>'''

IOCs are usually run in screen or procServ so that:
* the window in which they’re started can be closed
* multiple people can connect to them
* [procServ] allows other user accounts to restart an IOC
* [procServ] allows users to connect to Windows IOCs

==== Confirm the IOC is running ====

:'''<code>kmp status</code>'''
:<code>kmp is running (pid=1281733) in a screen session (pid=1281732)</code>

Note: bugs in the deployed copy of '''<code>xxx.sh</code>''' may prevent it from detecting an IOC is running.

 

=== Connecting to an IOC’s shell ===

There are many ways to do it:

* Manually connect to an IOC running in screen from the IOC’s host
::<code>$ '''screen -x kmp'''</code>
::The -x option will connect even if someone is already connected to the screen session.
::The -r option only succeeds if no one is connected to the session.

* Connect to an IOC running in screen or procServ from the IOC’s host
::<code>$ '''kmp console'''</code>

* Connect to an IOC running in screen or procServ with logging '''from any host'''
::<code>$ '''/APSshare/bin/iocConsole.py iockmp'''</code>
::Note: iocConsole.py requires ssh access which beamline accounts don't have by default

* Manually connect to an IOC running in procServ from the IOC’s subnet
::<code>$ '''telnet s100bcda 53127'''</code>

=== Disconnecting from an IOC’s shell ===

* '''Close the terminal''' that is connected to the screen or procServ session
** Disconnects from both screen & procServ
** Kills an IOC running outside of screen & procServ
* '''<code>Ctrl+a</code>''', '''<code>Ctrl+d</code>'''
** Disconnects from both screen & procServ
** Kills an IOC running outside of screen & procServ
* '''<code>Ctrl+a, d</code>'''
** Only disconnects from screen

=== IOC shell commands ===

See [https://wiki-ext.aps.anl.gov/blc/index.php?title=EPICS_Cheat_Sheet EPICS Cheat Sheet]

 
== Where does EPICS support reside at the APS ==
 
[[File:IOC_Support.jpg|center|thumb|500px]] 

== What's next? ==
For step by step instructions to create your own IOC, go to [https://git.aps.anl.gov/practical_beamline_controls_training/session_2/instructions IOC Deployment & Troubleshooting].

Git 101

2023-12-01T17:33:36Z

Rodolakis: /* Your branch and 'origin/main' have diverged */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** For more info on addressing conflict, see [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:32:46Z

Rodolakis: /* Your branch and 'origin/main' have diverged */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have '''diverged'''. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:32:08Z

Rodolakis: /* Your branch is ahead of 'origin/main' */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''ahead''' of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:31:57Z

Rodolakis: /* Your branch is behind 'origin/main' */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is '''behind''' <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:31:13Z

Rodolakis: /* Your branch is ahead of 'origin/main' */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits ''locally'' that are not yet in the <code>main</code> branch on the ''remote'' repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:28:51Z

Rodolakis: /* Typical Branching Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch ''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:21:37Z

Rodolakis: /* Git Workflow Components */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the ''local'' <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the ''remote'' <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T17:21:09Z

Rodolakis: /* Git Workflow Components */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name it <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T16:58:47Z

Rodolakis: /* Basic Commands */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit, in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (merging) them into your local repository.
* <code>git pull</code> = <code>git fetch</code> + <code>git merge</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on.

=== Upstream Branch ===

* The instructions provided here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the '''upstream''' for your branch.
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to <code>pull</code>/ <code>fetch</code> / <code>push</code> the changes from / to.
* To resolve this, you can either set the upstream branch as suggested in the error message, or '''specify the remote name and branch''' (typically <code>origin</code> and <code>main</code>, respectively) '''every time''' you <code>pull</code>/ <code>fetch</code> / <code>push</code>.
** To specify the remote & branch name: <code>$ git fetch/pull/push origin <branch_name></code>
** Or to set the upstream, you would use: <code>$ git push -u origin <branch_name> </code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T16:38:58Z

Rodolakis: /* Branching for IOCs Upgrade */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

You are now ready to upgrade the <code>synApps_6_2/ioc</code> directory from <code>synApps_6_1</code> to <code>synApps_6_2</code>.

'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
* In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch (associated to the remote branch <code>origin/synApps_6_1</code>).
* In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch (associated to the remote branch <code>origin/main</code>).

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T16:33:55Z

Rodolakis: /* Version Control for EPICS IOCs */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== Version Control for EPICS IOCs ===

Initialize the local repository:

$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitattributes . # copy from .gitattributes xxx
$ cp /APSshare/epics/synApps_6_2_1/support/xxx-R6-2-1/.gitignore . # copy from .gitignore 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:''' very important '''Uncheck initialize repository''' (to avoid conflict between local and remote)
* '''Create project'''
* '''Clone drop-down''' (blue button, right hand-side): copy the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T16:31:32Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [https://wiki-ext.aps.anl.gov/blc/index.php?title=Git_101#Upstream_Branch Upstream Branch].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-12-01T16:30:48Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git status # Check the status of your local repo
$ git pull # Pull the latest changes from the remote

* To commit a new file:
$ 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 at once:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:28:26Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:28:21Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:.

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:28:07Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:28:01Z

Rodolakis: /* Basic Commit Workflow */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:.

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:27:17Z

Rodolakis: /* Upstream Branch */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:27:09Z

Rodolakis: /* Upstream Branch */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below)..
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].

Git 101

2023-11-29T21:26:53Z

Rodolakis: /* Upstream Branch */

== Practical Step-by-Step Examples ==
 

=== Basic Commit Workflow ===

This <code>(pull-)edit-add-commit(-push)</code> recipe is all you need for 95% of projects:

* To sync your local repository with the remote repository:
$ git checkout main # Switch to (or confirm you 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:
<code> $ git commit -am 'Description of changes'</code>

* To push your changes to the remote repository:
<code> $ git push</code>

'''Note:''' This workflow assumes you are working with the <code>main</code> branch, and that <code>origin/main</code> has been set as the [[Upstream Branch]].

 

=== 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 the '''SSH''' remote URL <code>git@git.aps.anl.gov:29id/myioc.git</code>

Back to the local repository, add the reference to the new remote repository:

$ git remote add origin git@git.aps.anl.gov: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 it as the upstream

 

=== Branching for IOCs Upgrade ===

* Make sure your local repository in <code>synApps_6_1</code> 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 <code>synApps_6_1</code> (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 origin/synApps_6_1 as the upstream for this branch

* Clone the IOC repository into the <code>synApps_6_2</code> directory:
$ cd ../../../synApps_6_2/ioc/ # Navigate to the synApps_6_2/ioc directory
$ git clone git@git.aps.anl.gov:29id/myioc.git # Clone the repository

*'''Note:''' the new <code>main</code> branch now points to the <code>synApps_6_2</code> directory:
** In the directory <code>synApps_6_1/ioc/myioc</code>, you will be working on the <code>synApps_6_1</code> branch.
** In the directory <code>synApps_6_2/ioc/myioc</code>, you will be working on the <code>main</code> branch.

 
 

== Basic Commands ==
 

=== Viewing Changes and Status ===
* To switch to the <code>main</code> branch:
<code>
$ git checkout main
</code>
* To see the status of the working directory and staging area (also confirm the current branch you are on):
<code>
$ git status
</code>
* To list the commit history:
<code>
$ git log
</code>
* To view differences since the last commit:
<code>
$ git diff <file>
</code>
* To see tracked files:
<code>
$ git ls-files
</code>

=== Committing Changes ===
* To commit a single tracked file (add 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 <code>-a</code> (add to staging area and commit in a single step):
<code>
$ git commit -am 'commit message'
</code>

=== Ignoring Files ===
<code>.gitignore</code> 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:
<code>
$ git fetch
</code>

* To fetch changes from the remote repository and merge them into your current branch:
<code>
$ git pull
</code>

* To push local commits to the remote repository:
<code>
$ git push
</code>

* To list the remote repositories and their URLs:
<code>
$ git remote -v
</code>
 
 
=== Upstream Branch ===

* The instructions provided in here assume that <code>origin/main</code> (the main branch of the remote repository) is already set as the upstream for your branch (more info below).
* If an upstream branch has not been set, you will encounter errors when attempting to <code>pull</code>, <code>fetch</code> or <code>push</code>:
fatal: The current branch has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin <branch_name>
* This message is Git's way of telling you that it does not know where to fetch/pull/push the changes from/to.
* To resolve this, you either set the upstream branch as suggested or specify the remote name and branch (typically <code>origin</code> and <code>main</code>, respectively) every time you pull or push.
** For setting the upstream, you would use: <code>$ git push -u origin <branch_name> </code>
** Or specify the remote and branch name: <code>$ git fetch/pull/push origin <branch_name></code>

* The <code>-u</code> flag stands for <code>--set-upstream</code>:
** This flag is used to set a relationship between your local branch and a remote branch: <code>origin/main</code> is now the upstream for your current local branch.
** Once the upstream is set, you can use <code>pull</code>, <code>fetch</code> or <code>push</code> '''without specifying the remote name and branch'''. Git will automatically know that you're referring to <code>origin/main</code>.

 

=== Git Fetch vs. Git Pull ===
* <code>git fetch</code>: '''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 (pulling) them into your local repository.
* <code>git pull</code>: not only '''downloads''' changes from the remote repository but also immediately attempts to '''merge''' them into the branch you are currently working on:<code>git pull</code> = <code>git fetch</code> + <code>git merge</code>.

=== Custom aliases ===

$ git config --global alias.st 'status' # create an alias git st = git status
$ git config --global --list # see list of aliases
$ git config --global --replace-all alias.lg # may need replace-all flag
# to overwrite existing aliases
#### Common aliases:
$ alias.br 'branch'
$ alias.ci 'commit'
$ alias.co 'checkout'
$ alias.st 'status'
$ alias.df 'diff'
$ alias.ft 'fetch'
$ alias.lg "log -10 --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

This last command sets a global alias <code>lg</code> for git, which transforms the output of git log into a visually structured and color-coded format, displaying the last 10 commits.

 
 

== Git Workflow Components ==
 

[[File:git_101.jpg|thumb|center|900px]]
 
* '''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 <code>push</code> and <code>pull</code> commands.

'''Note:''' For the longest time, the default branch in most Git repositories was named <code>master</code>; the convention is now to name is <code>main</code>. To rename the local <code>master</code> branch:

<code>$ git branch -m master main</code>

To rename the remote <code>master</code> branch, see [https://www.git-tower.com/learn/git/faq/git-rename-master-to-main 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. <code>temp/</code>, <code>auto_settings.sav*</code>, <code>auto_positions.sav*</code>, 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.
* '''Why stage?''' 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.
 
=== Git add ===
The <code>git add</code> 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 <code>git add <filename></code> 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), <code>git add <filename></code> starts tracking these files in addition to staging them. From this point onward, any changes to these files will be recognized by Git.

 
 

== Branching Basics ==
 
[[File:Git_branching.jpg|thumb|center|600px]]

=== Branching 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 Branching Workflow ===

* Create a new branch from the <code>main</code> branch:
$ git checkout main # Switch to (or confirm you are on) the main branch
$ git pull # Ensure it's up to date with the remote
$ git checkout -b new-branch # Create a new branch and switch to it
Note that because of the <code>-b</code> option in <code>git checkout -b new-branch</code>, this command is equivalent to <code>git branch new-branch</code> + <code>git checkout new-branch</code>, i.e. create a branch '''and'' switch to it.

* 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 <code>main</code> 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 <code>main</code>. Replace main with the appropriate branch name if different in your repository.

 
 

== Troubleshooting ==

 
=== 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 <code>main</code> branch.
* '''Branch Status''': Your <code>main</code> branch is up to date with <code>origin/main</code> (the main branch from the remote repository).
* '''Changes to be Committed''':
** <code>file1</code> has been modified and <code>file2</code> is a new file, both staged for the next commit.
** To unstage, use <code>git reset HEAD <file></code>.
* '''Changes Not Staged for Commit''':
** <code>file3</code> is modified but not staged.
** To stage, use <code>git add <file></code>.
** To discard changes, use <code>git checkout -- <file></code>.
* '''Untracked Files''':
** <code>temp/</code> and <code>notes.txt</code> are not tracked by Git.
** To track, use <code>git add <file></code>.
** To ignore, add them to the <code>.gitignore</code> 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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is ahead of <code>origin/main</code> by 3 commits. This means you have made commits locally that are not yet in the <code>main</code> branch on the remote repository.
** To synchronize these changes with the remote repository, use <code>git push</code>.
* '''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 <code>main</code> branch.
* '''Branch Status''':
** Your <code>main</code> branch is behind <code>origin/main</code> 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 <code>origin/main</code> using <code>git pull</code>.
* '''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 <code>main</code> branch.
* '''Branch Divergence''':
** Your local <code>main</code> branch and remote <code>origin/main</code> branch have diverged. This means there are different commits in both branches that are not in the other.
* '''Merge Conflict''':
** A merge conflict has occurred in <code>conflicted_file.txt</code> 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 <code>git add <file></code> to mark the conflict as resolved.
** After resolving the conflict, complete the merge by committing the changes with <code>git commit</code>.
** If you wish to cancel the merge, use <code>git merge --abort</code>.
* '''Working Tree Status''':
** Address the merge conflict before proceeding with other Git operations.
** More info [https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts here].