howto: git (github) usage

Message
Author
skidoo
Posts: 753
Joined: Tue Sep 22, 2015 6:56 pm

howto: git (github) usage

#1 Post by skidoo »

asking howto (and BestPractices advice) b/c forum search "git or github, topic titles" only returned these 2 topics:
MX 15 Repository: The git-cola Thread http://forum.mxlinux.org/viewtopic.php?f=121&t=39892
Announcement - the MEPIS-Community github organisation (2011)
http://forum.mxlinux.org/viewtopic.php?f=77&t=29308

I've already installed git & have used it a few times (forked a few existing repos at github, cloned locally, committed/pushed babystep changes upstream) but have several questions regarding BestPractices, and... when someone (vinv?) recently asked "how to get involved", I was stunned that no one mentioned https://github.com/MX-Linux

related: The wonderfully-detailed MX UserManual, crammed all into a single html page, is becoming unwieldy.
A github repo does not yet exist for MXdocs, AFAICT. That (a github repo) could facilitate both contribs and bugs/change requests.

a few questions from a git noob:
Where should local git-cloned projects reside? Under user's home directory? Under root user's home? Does it even matter?
Does it matter who owns the files? Does git "know/care" whether each given file should be chmod 744 or whatnot?
How should paths for each local repo be structured? If a file is ultimately destined for /usr/share...
that path should (must?) be represented in the local repo, ala ~/git/projectname/projectname-master/usr/share/... ?

User avatar
Adrian
Developer
Posts: 8250
Joined: Wed Jul 12, 2006 1:42 am

Re: howto: git (github) usage

#2 Post by Adrian »

We have this: https://mxlinux.org/wiki/system/git but that's just the bare minimum intro to git...
We used to have the manual on Github, not sure why that is not used anymore maybe the writer found git a bit unyielding...
Where should local git-cloned projects reside? Under user's home directory? Under root user's home? Does it even matter?
In a place where you have access without having to su to root, home is fine or any subfolder in your home.
Does it matter who owns the files? Does git "know/care" whether each given file should be chmod 744 or whatnot?
Git preserves the file attributes, if the file is executable or not, not sure exactly what it does about ownership, it probably preserves the uid.
How should paths for each local repo be structured? If a file is ultimately destined for /usr/share...
Not sure how you want to add it to /usr/share, if it's part of a package that is something that debuild is taking care of you have a debian/install file that tells dpkg where to place the file.
that path should (must?) be represented in the local repo, ala ~/git/projectname/projectname-master/usr/share/... ?
no, again it depends how you want to add it, if you use a debuild to build a .deb it doesn't matter where you have the file, although it might be a good idea to have a similar structure to make it easy for you or whoever else uses the repo to figure out where the file goes without examining debian/install file so it might be a good idea to have a usr/share folder in your repo.

User avatar
Adrian
Developer
Posts: 8250
Joined: Wed Jul 12, 2006 1:42 am

Re: howto: git (github) usage

#3 Post by Adrian »

BTW, I wrote a number of times a intro to Git and Github for the Devs, I will look for that and post here. I can also respond to any question you might have.

User avatar
Jerry3904
Administrator
Posts: 21881
Joined: Wed Jul 19, 2006 6:13 am

Re: howto: git (github) usage

#4 Post by Jerry3904 »

On git(hub), there is this nice overview in the Wiki (originally written by Adrian, I think):

https://mxlinux.org/wiki/system/git
The wonderfully-detailed MX UserManual, crammed all into a single html page, is becoming unwieldy.

A github repo does not yet exist for MXdocs, AFAICT. That (a github repo) could facilitate both contribs and bugs/change requests.
All true. I have just not wanted to take the time and make the effort to learn how to do it, and then to change the current system. It is all I can do ATM to keep up with a volatile text like that. I have considered just putting Section 3 up, since it by far takes up most of the change log.

The MXUM is on a single page so Ctrl-F works. There are other ways to do it, but they get complicated quickly when more than one file is involved. Again, it's a question of minimizing the time/effort I need to invest to get the work done.

BTW: if you would like to work on the Wiki, another volatile text, I would be happy to have you involved.
Production: 5.10, MX-23 Xfce, AMD FX-4130 Quad-Core, GeForce GT 630/PCIe/SSE2, 16 GB, SSD 120 GB, Data 1TB
Personal: Lenovo X1 Carbon with MX-23 Fluxbox and Windows 10
Other: Raspberry Pi 5 with MX-23 Xfce Raspberry Pi Respin

User avatar
Adrian
Developer
Posts: 8250
Joined: Wed Jul 12, 2006 1:42 am

Re: howto: git (github) usage

#5 Post by Adrian »

Here you go, this is what I wrote 2 years ago, I will take a look to see if anything changed.

This is a short git/github tutorial.

Please start to use the nice tools we have available for free to contribute code, once you get the hang of it, it makes it much easier to collaborate and work in a distributed fashion than passing around tarballs, downloading them, untarring, finding which files were changed, what was changed, etc.

Setup:
0. create github.com account if you don't have one
1. fork the github repo that you want to work upon in the github interface (this will give your own repo where you can make changes and try things on your own)
2. git clone yourgithubrepo (you get the yourgithubrepo from github interface, this creates a local folder with the files from the repo)
3. cd to the new folder created by the previous command
4. git remote add upstream upstreamgithubrepo (the uptreamgithubrepo is the one that you forked from, makes it easier to track changes in the upstream)

Workflow:
1. git fetch upstream (to get any changes from upstream before committing)
2. git merge upstream/master (to merge the changes)
Alternatively, you can run one command "git pull upstream master" instead of fetch and merge, make sure though you don't have any uncommitted changes, this will wipe them.
3. work on the project: modify, add, remove files
4. git add . (or "git add filename") to track the changed files
5. git rm filename (to remove files)
6. git commit -m "descriptive commit message"
7. git push origin master (this pushes master branch to your github repo, you can also push other branches than master)
8. from Github you click on green Compare, Review, create Pull Request and create a pull request for the person who manages the upstream repo to pull your changes in their repo.

Useful git commands:
git status (shows you which files were modified which files are untracked)
git diff (shows diffs between your changed files and the last commit)
git log (shows the commits)
git diff HEAD^ (shows the difference from the previous commit)
git checkout -- filename (reverts the file to the version from the commit, useful if you messed up and you want the original file)
git checkout -- . (reverts all files, all changes since commit are lost)
git checkout branchname (change branch, add -b switch if the branch doesn't exist yet and you want to create it)

I'm pretty much following this workflow: http://openshift.github.io/documentatio ... guide.html

Please let me know if something is unclear or I missed a step. It might look complicated, but it's just a number of logical steps that once you start to use they are going to become second nature... so please don't be intimidated by this.

You can also use GUI helpers like gitk or qgit.

skidoo
Posts: 753
Joined: Tue Sep 22, 2015 6:56 pm

Re: howto: git (github) usage

#6 Post by skidoo »

Not sure how you want to add it to /usr/local/share
I could have phrased the question to better reflect my intent. Instead of creating "a whole new repo" (and new, separate packages to maintain), ISTM a lot of contribs could be piggybacked into existing packages. Of course the right of denial rests with upstream maintainers, but "desktop-defaults" or whichever existing packages could serve as vehicles to "little contribs", for example: half dozen new games (tiny pygtk scripts + accompanying .desktop files).
Does it matter who owns the files? Does git "know/care" whether each given file should be chmod 744 or whatnot?
Git preserves the file attributes, if the file is executable or not, not sure exactly what it does about ownership, it probably preserves the uid.
Today's video & discussion about symlinking select home subfolders to locations on an NTFS partition added to my wonderment about how git manages permissions/ownership when a commit is posted by a windows-native git client.
time and make the effort to learn how to do it, and then to change the current system.
It is all I can do ATM to keep up with a volatile text like that.
I fully respect that point.
I've been struggling to find which-end-up, toward assisting in updating the antiX docs.
Even though they are, comparatively, static, [headspin] how much detail for a given subject is enough? How much is TOO much?
Then there's the separate (beyond my ability) task of managing translations...

Food for thought:
a lot of content (look past the presentation/glitz) can be gleaned from, or modified from, other xfce-centric distros, e.g.
LinuxLiteOS UserManual https://www.linuxliteos.com/manual/
Their chosen license is GPLv2 (vs MX is GPLv3?) which precludes seamless collaboration, but could provide a starting point
https://github.com/linuxlite/litemanual
for a multi-page framework. Ultimately, the cat's pajamas (IMO) would be local docsearch capability, ala aptosid
(using "recoll" indexer to achieve an offline search for the user manual) http://manual.aptosid.com/en/manual-search-en.htm

User avatar
Gordon Cooper
Posts: 965
Joined: Mon Nov 21, 2011 5:50 pm

Re: howto: git (github) usage

#7 Post by Gordon Cooper »

@ Adrian. Some months ago you wrote a brief tutorial on using github . When you have the time I would appreciate a bit more detail please. Am working on the manual, having joined as a contributor, set up a github account and repo, then created a Branch of Jerry's mxum repo. Have a copy of the files in a folder. Getting confused with making modifications to these files. Can edit those in the folder, no problem, but what happens next? Tried adding a modified file to the Branch, it appeared to be added, but the file in the Branch repo has not been changed. Should the original be deleted first? Also ran into a wall when trying to commit a descriptive comment to explain the changes.

Got a 404 error when trying to read this guide that you suggested.
I'm pretty much following this workflow: http://openshift.github.io/documentatio ... guide.html
Backup: Dell9010, MX-19_B2, Win7, 120 SSD, WD 232GIB HD, 4GB RAM
Primary :Homebrew64 bit Intel duo core 2 GB RAM, 120 GB Kingston SSD, Seagate1TB.
MX-18.2 64bit. Also MX17, Kubuntu14.04 & Puppy 6.3.

User avatar
Jerry3904
Administrator
Posts: 21881
Joined: Wed Jul 19, 2006 6:13 am

Re: howto: git (github) usage

#8 Post by Jerry3904 »

Let's see if I understand where you are stuck, since I *own* your upstream github repo. Here is the modification of Adrian's instructions I made for our situation, with a couple of comments on stuff I ran into:
First time setup:
1. git clone https://github.com/jerry3904/mxum
(this creates a local folder with the files from my repo)
2. cd to the new folder created by the previous command
3. git remote add upstream https://github.com/jerry3904/mxum (makes it easier to track changes in the upstream)

Workflow:
1. git fetch upstream (to get any changes from upstream before committing)
2. git merge upstream/master (to merge the changes)
--If you have not made any changes since you last issued a pull request, you can run one command "git pull upstream master" instead of fetch and merge (make sure though you don't have any uncommitted changes).
3. work on the project: modify, add, remove files
4. git add . (or "git add filename") to track the changed files
-- git rm filename (to remove files)
5. git commit -m "descriptive commit message" (indicate what you have changed so we know what it's about)
6. git push origin master (this pushes master branch to your github repo, you can also push other branches than master)
<< (Jerry) this may take some time to show up for you in NZ, it seemed slow to me from here
7. from Github you click on green "Compare, Review, create Pull Request" and create a pull request for me to pull your changes into my repo.
So my questions to see more exactly where the problems arose:

--were you able to do the steps in First-time setup?
--any problem with the first two steps in Workflow?
--what about steps 4-6 after you finished your work?
--did you click on that button in step 7? I didn't receive a pull request to bring your changes up to my branch so if you did then that step may need to be repeated. I had a bit of trouble with this step the first time, and actually cancelled my pull request to the upstream master by mistake.

BTW: commands from 3 onward are issued in a terminal opened in the folder created in step 2.
Production: 5.10, MX-23 Xfce, AMD FX-4130 Quad-Core, GeForce GT 630/PCIe/SSE2, 16 GB, SSD 120 GB, Data 1TB
Personal: Lenovo X1 Carbon with MX-23 Fluxbox and Windows 10
Other: Raspberry Pi 5 with MX-23 Xfce Raspberry Pi Respin

User avatar
Gordon Cooper
Posts: 965
Joined: Mon Nov 21, 2011 5:50 pm

Re: howto: git (github) usage

#9 Post by Gordon Cooper »

Thanks Jerry, Setup no problems, I have a local folder with a copy of your files. i can work on these with suggested changes. Getting stuck on the merge/commit steps. . Will work on it in an hour or two, weather has come right and have some chores - heatpump filters for a start,
Gordon.
Backup: Dell9010, MX-19_B2, Win7, 120 SSD, WD 232GIB HD, 4GB RAM
Primary :Homebrew64 bit Intel duo core 2 GB RAM, 120 GB Kingston SSD, Seagate1TB.
MX-18.2 64bit. Also MX17, Kubuntu14.04 & Puppy 6.3.

User avatar
Gordon Cooper
Posts: 965
Joined: Mon Nov 21, 2011 5:50 pm

Re: howto: git (github) usage

#10 Post by Gordon Cooper »

Have sent Jerry a post about progress here. As others may be interested, herewith a copy.
"
Stalling on the push to your github repo. here is latter part of
the terminal action, all appears to be going well until permission
denied. Must be doing something wrong but it is not obvious to me.
Think it may be a clash between me as a collaborator and Adrian's
instructions, which may be for general usage and not for a collaborator?

Gordon.

"git config user.email HughGordonT@gmail.com
[1]+ Exit 2 git config --global email HughGordonT
gordon@gordondesktop:~/mxum
$ git config user.name tuxfordc
gordon@gordondesktop:~/mxum
$ git commit -m "removed 2 lines before 1.2 Subheading. These credits already in About Us."
[master ac5417f] removed 2 lines before 1.2 Subheading. These credits already in About Us.
1 file changed, 0 insertions(+), 0 deletions(-)
gordon@gordondesktop:~/mxum
$ git push origin master
Username for 'https://github.com': tuxfordc
Password for 'https://tuxfordc@github.com':
Counting objects: 3, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 18.90 KiB | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To https://github.com/jerry3904/mxum
! [remote rejected] master -> master (permission denied)
error: failed to push some refs to 'https://github.com/jerry3904/mxum'
gordon@gordondesktop:~/mxum"

Later thoughts : The only change I made to the LO file S1.odt was the removal of two lines which appeared to be a duplication. However if this file
is merged with the original file, then these two lines may be re-instated ? mmmmm....
Backup: Dell9010, MX-19_B2, Win7, 120 SSD, WD 232GIB HD, 4GB RAM
Primary :Homebrew64 bit Intel duo core 2 GB RAM, 120 GB Kingston SSD, Seagate1TB.
MX-18.2 64bit. Also MX17, Kubuntu14.04 & Puppy 6.3.

Post Reply

Return to “General”