From: Shourya Shukla <email@example.com> To: Junio C Hamano <firstname.lastname@example.org> Cc: email@example.com Subject: Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section Date: Tue, 21 Apr 2020 12:28:53 +0530 [thread overview] Message-ID: <20200421065853.GA11800@konoha> (raw) In-Reply-To: <firstname.lastname@example.org> On 16/04 12:05, Junio C Hamano wrote: > Shourya Shukla <email@example.com> writes: > "to ignore files from getting tracked in the working tree" is why > you may want to use the '.gitignore' file. That is OK. But the > connection to the next sentence, especially the subject "This > ignores", is hard to grok. I am guessing that you want to tell the > users something like > > Paths that match patterns listed in the `.gitignore` are > not meant to be tracked. > > The act of adding a pattern in `.gitignore` that matches a > set of paths that are not tracked is a declaration that you > do not intend to track these paths and a request by you to > Git to help you achieve that goal. > > but you are trying to state it in a more approachable manner. But I > sense that you ended up being unclear. I apologise for this. I am understanding the concepts but I fail to put them in words in English. I will try my best to not degrade the quality of important documentation such as this one. > This part is very much in line with the "you are declaring and > requesting". The user does not want to track these paths > Having commented on this section, I am not sure why we need so much > description here, instead of clarifying the existing documentation > of the mechanism in the Documentation/gitignore.txt file. > > I think it is better to limit the FAQ list to two kinds of entries: > > * A topic that spans multiple mechanisms and features that is not > easy to explain in a single documentation page may have to be > described in place. > > * Other topics that already have authoritative description with > adequate clarity in other pages should just have a summary > paragraph that is less than 5 sentences, and a pointer to the > authoritative page. > > The `.gitignore` topic should fall into the latter category. It is > a separate issue if Documentation/gitignore.txt has rooms for > improvement and if so, I think it is more productive to propose a > patch to it there, not adding too much description on the topic > here. I have seen this problem occur a lot so I decided to put it in the FAQ. I will try to shorten it and make it more 'to the point'. Regards, Shourya Shukla
next prev parent reply other threads:[~2020-04-21 6:59 UTC|newest] Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-04-13 14:09 [PATCH v2 0/1] update gitfaq Shourya Shukla 2020-04-13 14:09 ` [PATCH v2 1/1] gitfaq: append the 'Common Issues' section Shourya Shukla 2020-04-14 1:06 ` brian m. carlson 2020-04-14 7:33 ` Junio C Hamano 2020-04-16 19:05 ` Junio C Hamano 2020-04-21 6:58 ` Shourya Shukla [this message] 2020-04-16 19:36 ` Junio C Hamano 2020-04-21 0:57 ` Junio C Hamano 2020-04-21 8:38 ` Shourya Shukla 2020-04-21 18:00 ` Junio C Hamano -- strict thread matches above, loose matches on Subject: below -- 2020-04-13 10:55 [PATCH v2 0/1] update gitfaq Shourya Shukla 2020-04-13 10:55 ` [PATCH v2 1/1] gitfaq: append the 'Common Issues' section Shourya Shukla
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200421065853.GA11800@konoha \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH v2 1/1] gitfaq: append the '\''Common Issues'\'' section' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).