git, simplified
Perhaps you’ve come across a great cache of publicly available SQL scripts that would be very useful in monitoring your databases, and these scripts are hosted on github. Getting those scripts is as simple as clicking the Download button.
What if, however, you wish to contribute to the script library?
Or perhaps you would like to collaborate with coworkers on a project and want to host the files on github.
How do you get the files to your local server so that changes can be saved and pushed to the master repo?
Github is often the answer for that.
Some time ago github was probably considered by most IT folks as a tool for developers. That has changed, as now git and github are popularly used to manage changes and allow collaboration on many kinds of projects that require file management.
If you are reading this blog, you are probably a DBA. What better way to manage SQL scripts and allow others to contribute than with github?
Let’s simplify the use of git and make it usable for casual users. In other words, DBAs who want to access a SQL repo, and don’t want to relearn git every time, need to access the repo.
The methods shown here are not the same ones that would be used by a team of developers. Typically developers would create a fork of a project, clone that fork, modify files, and then issue pull requests to the main repo owner. There would also be branches to the development tree, merging, etc.
For this demo, there will still be a need to fork your own copy of the repo, but that is as far as it will go at this time.
Read more about creating a fork: https://help.github.com/articles/fork-a-repo/
In the spirit of keeping this simple, there will be no branching in this demo; I’ll only show the basics required to contribute to a project.
With simplicity as a goal, the following steps are to be performed in this demo:
- Create a copy (fork) of the main repo in github
- Clone the repo to a work environment (my linux workstation)
- Add a file to the local repo
- Commit the changes and push to my forked repo on github
- Issue a ‘pull request’ asking the main repo admin to include my changes
So while it will be necessary to create a fork of the project, we won’t be dealing with branches off the mainline.
Assumptions:
– you already have a github account
– git is installed on your laptop, server, whatever.
Git Repos
Two users will be used for this demo: jkstill and pytest.
The following repos will be used.
Main Repo: https://github.com/jkstill/git-demo
Developer’s (you) repo: https://github.com/pytest/git-demo
The Main Repo is public, so you can run this demo using your own account if you like.
Fork the Repo
The following steps were performed by the pytest user on github.
Login to https://github.com/ using a browser.
Navigate to https://github.com/jkstill/git-demo
Click on the ‘Fork’ icon and follow any instructions; this should only take a few seconds.
After forking this repo as pytest, my browser was now directed to https://github.com/pytest/git-demo
ssh key setup
This only needs to be done once.
The following examples are for github user pytest.
The pytest account will be used to demonstrate the concepts. Later I will explain more about ssh usage as it pertains to github, but for now this is probably sufficient.
create a new ssh key for use with github
ssh-keygen -t rsa -N '' -f ~/.ssh/id_rsa_pytest_github -C 'github'
add key to github account
While logged in to your github account in a browser, find the account settings icon.
The icon for account settings is in upper right corner of browser window.
Navigate to the Add SSH Key section.
account settings -> SSH Keys -> Add SSH Key
The key added will be the public key. So in this case, the contents of ~/.ssh/id_rsa_pytest_github.pub would be pasted in the the text box that appears when the Add SSH Key button is pushed.
authenticate to github – the ‘git@github.com’ is required
Make sure to authenticate the key with github.
ssh -i ~/.ssh/id_rsa_pytest_github -t git@github.com
Here is a successful example:
> ssh -i ~/.ssh/id_rsa_github -t git@github.com Host key fingerprint is DE:AD:BE:EF:2b:00:2b:36:63:1b:56:4d:eb:df:a6:42 +--[ RSA 2048]----+ | . | | + . | | . B . | | o * + | | Y * S | | + O o . . | | . Z . o | | . . t | | . . | +-----------------+ PTY allocation request failed on channel 0 Hi pytest! You've successfully authenticated, but GitHub does not provide shell access.
Clone the REPO
Now you are ready to clone the newly forked repo to your workstation. At this point, it is assumed that git is already installed in your development environment. If git is not installed then you will need to install it. There are many resources available whichever platform you are working on; installation will not be covered here.
The following command will clone your forked copy of the repo in the current directory:
> git clone https://github.com/pytest/git-demo Cloning into 'git-demo'... remote: Counting objects: 7, done. remote: Compressing objects: 100% (6/6), done. remote: Total 7 (delta 0), reused 7 (delta 0), pack-reused 0 Unpacking objects: 100% (7/7), done. Checking connectivity... done > cd git-demo /home/jkstill/github/pytest/git-demo > ls -la total 20 drwxr-xr-x 3 jkstill dba 4096 Aug 18 15:45 . drwxr-xr-x 4 jkstill dba 4096 Aug 18 15:45 .. drwxr-xr-x 8 jkstill dba 4096 Aug 18 15:45 .git -rw-r--r-- 1 jkstill dba 113 Aug 18 15:45 .gitignore -rw-r--r-- 1 jkstill dba 47 Aug 18 15:45 README.md
Note: it is possible to use the ~/.ssh/config file to specify multiple ssh keys for use with git. This is useful when you may be using multiple accounts.
The command I used to do this operation is below as I do have multiple accounts:
git clone git-as-pytest:pytest/git-demo
You can read more about this in a later section of this article.
Now cd to the new repo: cd git-demo
There should be two files and a directory as seen in the previous example.
Modify or add a script
Now you can modify a script or add a new script and then commit to your local repo.
In this case, we will add a script fra_config.sql to the local repo.
-- fra_config.sql
-- show location and size of FRA
col fra_location format a30
col fra_size format a16
select fra_location, fra_size from (
select name, value
from v$parameter2
where name like 'db_recovery_file_dest%'
)d
pivot ( max(value) for name in (
'db_recovery_file_dest' as FRA_LOCATION,
'db_recovery_file_dest_size' as FRA_SIZE
)
)
/Modified files can be seen with git status:
> git status # On branch master # Untracked files: # (use "git add <file>..." to include in what will be committed) # # fra_config.sql nothing added to commit but untracked files present (use "git add" to track) Now add the file to the list of those that should be tracked and check the status again: > git add fra_config.sql > git status # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # new file: fra_config.sql #
As we are happy with the results, it is time to commit to the local repo:
> git commit -m 'Added the new file fra_config.sql' [master 86eaf7c] Added the new file fra_config.sql 1 file changed, 18 insertions(+) create mode 100644 fra_config.sql > git status # On branch master # Your branch is ahead of 'origin/master' by 1 commit. # (use "git push" to publish your local commits) # nothing to commit, working directory clean
Shouldn’t we have put a date in that file? OK, a date and time was added, changes to the file displayed, the file was added to the list of those to commit, and the commit made:
> git diff fra_config.sql | cat diff --git a/fra_config.sql b/fra_config.sql index 03b98fd..37c58ac 100644 --- a/fra_config.sql +++ b/fra_config.sql @@ -1,6 +1,7 @@ -- fra_config.sql -- show location and size of FRA +-- jkstill 2015-08-18 16:03:00 PDT col fra_location format a30 col fra_size format a16 > git add fra_config.sql > git commit -m 'added timestamp' [master 83afd35] added timestamp 1 file changed, 1 insertion(+) > git status # On branch master # Your branch is ahead of 'origin/master' by 2 commits. # (use "git push" to publish your local commits) # nothing to commit, working directory clean
Committing can and should be done frequently, as the commit affects only the local repository.
This makes it possible to see (and retrieve) incremental changes to a file as you work on it.
Once you are satisfied with all changes, push the changes to the repo. Notice that git status knows that 2 commits have been performed locally that are not seen in the master repository.
Configure the Remote
Before pushing to the main repo, there is a little more configuration work to do. While this method is not strictly necessary, it does simplify the use of git.
You will need to edit the file ~/.ssh/config; create it if it does not already exist.
Here’s my example file where a host git-as-pytest has been created. This host will be used to connect to github.
GSSAPIAuthentication no VisualHostKey=yes Host git-as-pytest HostName github.com User git IdentityFile /home/jkstill/.ssh/id_rsa_pytest_github IdentitiesOnly yes
Now edit the file ./.git/config. Find the line that remote “origin” and change the URL as seen in this example.
[core] repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true [remote "origin"] #url = https://github.com/pytest/git-demo url = git-as-pytest:pytest/git-demo.git fetch = +refs/heads/*:refs/remotes/origin/* [branch "master"] remote = origin merge = refs/heads/master
Now you should be able to push the changes to the master repo:
> git push origin master Counting objects: 7, done. Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 787 bytes | 0 bytes/s, done. Total 6 (delta 2), reused 0 (delta 0) To git-as-pytest:pytest/git-demo.git 788e5b1..83afd35 master -> master
The changes to your files can be seen in your repo on github.com
Issue a PULL request
Once you think the file or files are ready to be included in the master repository, you will issue a pull request to the admin of the master repo.
The repo admin can then pull the changes and examine them. Once it has been determined that the changes can be made to the master repo, the admin will push the changes.
Issuing the pull request
View the repo in your browser, press the ‘pull request’ icon and follow the instructions. This action will cause an email to be sent to the repo admin with URL to view the pull request. The admin can then examine and test the changes, and merge the pull request (if appropriate) into the mainline.
If the pull request results in your changes being merged, github will send you an email.
After the Pull request has been merged
Now other users can get the updates with the following commands
git pull git status git commit
These commands will merge the repo from github with this one.
As there is the possibility of overwriting files you are working on, be sure this is the right thing to do.
Now that you have the basics, you can get started.
Please feel free to use the https://github.com/jkstill/git-demo repo to follow along with the steps shown here.