Talk:Git
Exposition seems lacking
I used Git some years ago and was trying to refresh my memory by reading this article. I found it difficult to understand, although I don't know enough about Git to make the necessary edits here. For instance, under "Basic usage", I'm not really sure what a branch is, and especially, although it says "Create a branch to make changes", I don't know whether I actually need to make a new branch to make changes. How is "Merge commits back into the main branch" different from "Push changes to a remote server"? Under "Local repository", when I run "git init", what is that doing? I think it creates a .git directory but this could be explained a bit - what is it for, what does it contain. Next there is reference to an "index" or "staging area" - does this reside in .git? If so, perhaps we could mention that "git add" puts a copy of the specified files into somewhere in .git... Soon there is a reference to HEAD without explaining what HEAD is, but it seems important. Similarly "git mv" and "git ls-files" could have just a sentence explaining their difference to ordinary "mv" and "ls"... nothing huge, just a little context. Of course perhaps the problem is that I should read a tutorial (such as http://gitref.org/?) before reading the wiki article, but in that case it's a bit confusing that the wiki article has a style which at first seems introductory. Should we link to something like http://gitref.org/ at the top of the article? Herodotus (talk) 01:17, 16 July 2015 (UTC)
- (of course I would absolutely prefer for the Arch Wiki to have a superior Git Tutorial to anyone else) Herodotus (talk) 01:24, 16 July 2015 (UTC)
- The upstream docs are highly detailed, well explained, and offer everything from basic introductions to specialized use cases. This wiki page can not (and should not) compete here. As such, I'd suggest to remove most of the article, only referring to the relevant documentation. -- Alad (talk) 11:14, 16 July 2015 (UTC)
- Perhaps there could eventually be another Arch Wiki article with such a tutorial. I would be disinclined to make a rule like "no tutorials on the Arch Wiki". I also disagree about the Git documentation being well explained, I think there's too much of it to choose from, and that it tends not to answer basic questions at the beginning, and I think that a Wiki article has the potential to remedy both problems. Do Arch Wiki articles just explain installation and basic setup, plus tips and tricks? Theoretically the Wiki page could explain stuff like the fact that Git keeps a local copy of the revision history, unlike CVS etc.; that Git is snapshot-based, while Darcs is patch-based; that there is a specially-designed structure in
./.gitwhich supports certain operations efficiently; but I rarely see this kind of overview on Arch Wiki articles, so maybe it is not encouraged or supported. Herodotus (talk) 17:24, 16 July 2015 (UTC)
- Perhaps there could eventually be another Arch Wiki article with such a tutorial. I would be disinclined to make a rule like "no tutorials on the Arch Wiki". I also disagree about the Git documentation being well explained, I think there's too much of it to choose from, and that it tends not to answer basic questions at the beginning, and I think that a Wiki article has the potential to remedy both problems. Do Arch Wiki articles just explain installation and basic setup, plus tips and tricks? Theoretically the Wiki page could explain stuff like the fact that Git keeps a local copy of the revision history, unlike CVS etc.; that Git is snapshot-based, while Darcs is patch-based; that there is a specially-designed structure in
- There is already a rule: Help:Style#Hypertext_metaphor. That in no way implies there sould be "no tutorials on Arch Wiki", or that you should restrict yourself to installation+tips. What it does imply is what I said above - use the upstream documentation where possible. Simply copy/pasting a few commands for TL;DR purposes doesn't cut it.
- If you think there's too much too choose from, you can amend that with an introductory structure to the manuals in question; for an unrelated article but similar principle, see Midnight Commander. -- Alad (talk) 12:50, 17 July 2015 (UTC)
- Hi Alad, sorry for the long delay in replying. I felt I should fix this article and brush up on Git at the same time, so I put it off for a while. Thanks for the link to the style guide and the example. It sounds to me like we're pretty much in agreement, generally speaking, about Arch Wiki policy. I thought about removing the tutorial stuff from the Git article but I didn't have the heart to do that. I felt it would make the article less useful to me. Instead, I fixed the problems that I had encountered (as a new user) with the existing tutorial, by adding new information. I hope I didn't make it too much longer: here are the changes I made. I welcome constructive criticism... Please note that I have looked at quite a few existing tutorials, and none of them are as helpful to me as the present state of this article. It now answers a number of (what I felt to be) obvious questions, such as the purpose of "git mv" and the location of the "index". These answers were not in any other tutorial, and I had to resort to Google and Stackexchange to find them. However, it would be awkward to keep this useful information in the article without the existing tutorial structure. Herodotus (talk) 08:26, 1 September 2015 (UTC)
- I also came to this conclusion. Not only are the terms like "label", "index", "working tree", etc. really obscure, but just judging from the quite poor diversity of people doing changes (kind of like the Help articles), the whole thing seems so fat and filled that it would at least do good to do some re-ordering and sub-heading. First and foremost, I'd definitely like to see a better Git briefing and an explanation of the terms in the beginning of the article. Avoiding extra wording should, of course, be a consistent rule. It's not simplicity to explain any one thing in 4, albeit simple, different sentences. —Dettalk 13:06, 2 March 2016 (UTC)
- I think we all have different ideas of how this article should be best organized... In my view we should turn this into a real tutorial that starts a repo from scratch and adds 2 or 3 files and does simple stuff with them, explaining committing, branching etc. along the way, with brief explanations and links to the upstream docs for details. Then a second similar tutorial could be made to clone a repo and participate to an existing project, avoiding to restate what was already said in the first tutorial. — Kynikos (talk) 03:14, 3 March 2016 (UTC)
- Except we're duplicating efforts with git-scm - which is already superior in every way - just to cater to users who want a "short-cut" to the topic in question. None of the changes so far have convinced me otherwise (and git-scm keeps improving as well: see [1]). If we must keep this page, we should use it for strictly Arch-related content (perhaps a short AUR workflow) and rope to use upstream documentation if needed. -- Alad (talk) 22:15, 5 March 2016 (UTC)
- +1 on adding that. I'm serious, a bit of humor (cf. Creating packages for other distributions) doesn't hurt. :P -- Alad (talk) 04:17, 10 March 2016 (UTC)
- @Det: I thought that signature was what would have made the joke more complete, but apparently it's not so easy to get... ^^'
- It's up to Lahwaacz to add it or not, since he's the original author, or if he doesn't want to, with his permission I'll add it to my draft for the revised article, when I get to prepare it: I'm pretty sure that somebody with little sense of humor will soon remove it however, and when that happens I won't insist further by undoing the removal, it will just stay in the history of the page as another of this wiki's Easter eggs ;)
- — Kynikos (talk) 14:35, 15 March 2016 (UTC)
- Well, if the draft is going to be released on April 1, then I would probably agree :P Otherwise, Det was right. -- Lahwaacz (talk) 15:51, 15 March 2016 (UTC)
- Uh, now I fully understand your Machiavellian plans behind the creation of Template:Quote XD — Kynikos (talk) 04:12, 31 March 2016 (UTC)
- It has been 7 years since the last comment in this thread, is it safe to assume this issue has been solved? If so close the thread? Thanks PolarianDev (talk) 22:21, 11 June 2023 (UTC)
Deletion/editing of regurgitated docs
Hello,
The majority of Git#Usage is regurgitated from upstream. This is generally avoided within the archwiki as there is no point maintaining duplicate (and often less useful) documentation than upstream. So I suggest one of the following actions:
- Remove all the sections which are duplicates, and simply list to the general documentation (https://git-scm.com/docs)
- Remove the content of each section linking to the specific page within the documentation, for more precise docs.
Personally I believe the latter decisions would be better, otherwise its too 'RTFM', linking directly to upstream articles would make it a lot better, and we only need to document things if upstream doesn't, but due to how good the git documentation is, I am 99% sure that there is not a single thing we can add on, which upstream has not yet documented, it even has break downs on the git protocol.
This will also fix the expansion flag within the branch subsection, because we wouldn't need to expand on something which upstream has already explained very well.
Thank you,
PolarianDev (talk) 22:31, 11 June 2023 (UTC)